Debian Codegraph @

src/apps/moldft/fci/doc/matrixelements.tex

raw
1 \documentstyle [psfig,12pt,fleqn]{article}
2
3 \input{commands}
4 \input{bibstuff}
5
6 \newcommand{\RN}[1]{\underline{r}_{#1}}
7 \newcommand{\nCr}[2]{\left(\begin{array}{c} #1 \\ #2 \end{array}\right)}
8 \newcommand{\half}{\frac{1}{2}}
9
10 \title{Notes on the evaluation of coupling-coefficients and Hamiltonian matrix-elements using determinants and configuration state functions.}
11
12 \author{Robert J. Harrison}
13
14 \date{}
15
16 \begin{document}
17 \maketitle
18
19 \clearpage
20
21 \tableofcontents
22
23 \clearpage
24
25 \section{Introduction}
26
27 For the purpose of evaluating matrix elements over a wide variety of
28 density operators, while grouping all possible spin functions for a
29 given orbital occupation and also having the ability to use either CSF
30 or determinants, I have adapted a full-CI program that I wrote while at
31 Argonne National Laboratory in 1986/7. It has required some
32 modification for the present purposes and additional changes are
33 necessary, however, its internal structure is very simple and it
34 should be easy to extend, fast and correct!
35
36 These notes serve to describe the theory behind the code and the
37 coupling-coefficient generation and spin adaption used in the program.
38 The methodology is standard and draws very heavily upon Pauncz
39 \cite{pauncz,paunczsym}, Handy \cite{handyfci}, Knowles
40 \cite{knowleseai} and especially Duch
41 \cite{duchug,duchspinad,duchcouple,duchfci,duchsga}. Graphs provide a
42 very simple, visually accessible and computationally useful
43 representation of many types of bases, espcially of ``complete-bases''
44 such as full-CI, CISD, or all possible spin functions for a given
45 open-shell occupation. The graphical unitary group approach
46 \cite{paldusguga,shavittguga,shavittguga2} perhaps first demonstrated
47 the utility of this approach and it was applied in the symmetric group
48 approach by Duch et al \cite{duchsga}. The program internally uses
49 graphical representations only for the lexical ordering of orbital and
50 spin occupations. It does not use a graphical approach for the
51 evaluation of matrix elements. There is no advantage to this for FCI
52 and the modern thinking seems to be that graphical approaches of the
53 1970's and 1980's are unecessarily complex (c.f., the marvellous
54 analysis of the MRSDCI algorithm by Saunders and van Lenthe
55 \cite{saunders}).
56
57 I don't think that I have done anything new here. The notes are very
58 basic so that the program is usable even by someone unfamiliar with CI
59 methodology, or a graduate student.
60
61 \section{Determinant bases}
62
63 For the present purpose we shall assume that all molecular orbitals
64 ($\phi$) are real, orthonormal, and that spin orbitals ($\varphi$) are
65 constructed as a product of the spatial and spin components. For
66 instance,
67 \begin{equation}
68 \varphi_{i}(\RN{1}) = \phi_i(\RN{1}) \sigma_i(1)
69 \mbox{, $\sigma_i = \alpha$ or $\beta$}
70 \end{equation}
71 A determinantal electronic wavefunction ($\Phi$) is simply an
72 antisymmetrized product of spin orbitals:
73 \begin{eqnarray}
74 \Phi & = & \left| \varphi_{1}(\RN{1}) \varphi_{2}(\RN{2}) \cdots
75 \varphi_{n}(\RN{n}) \right | \\
76 & = & {\cal A} \; \varphi_{1}(\RN{1}) \varphi_{2}(\RN{2}) \cdots
77 \varphi_{n}(\RN{n}) \\
78 {\cal A} & = & \frac{1}{\sqrt{n!}} \sum_{P} (-1)^P P.
79 \end{eqnarray}
80 ${\cal A}$ is the antisymmetrizer and the sum in its definition ranges
81 over all possible $n!$ permutations of the $n$ electrons. When we
82 start evaluating matrix elements it will be important to note that the
83 permutations act on the electronic coordinates (space and spin) and
84 not on the labels of the orbitals.
85
86 A determinant is fully specified by
87 \begin{itemize}
88 \item the occupation of each spin orbital, and
89 \item an order in which the spin orbitals are occupied.
90 \end{itemize}
91 Clearly changing the order of the spin orbitals can change the sign of
92 the determinant, and thus consistency is crucially important.
93
94 One very common ordering, especially for full-CI programs
95 \cite{handyfci}, is to occupy all alpha spin orbitals before all beta spin
96 orbitals, and suborder by spatial orbital index within each group.
97 \begin{equation}
98 \underbrace{\phi_{1}(\RN{1})\alpha(1) \cdots
99 \phi_{n_{\alpha}}(\RN{n_{\alpha}})\alpha(n_{\alpha})}_{\mbox{Alpha orbitals}}
100 \underbrace{\phi_{n_{\alpha}+1}(\RN{n_{\alpha}+1})\beta(n_{\alpha}+1) \cdots
101 \phi_{n}(\RN{n})\beta_{n}(n)}_{\mbox{Beta orbitals}}
102 \end{equation}
103 The alpha or beta occupations are often referred to as strings. This
104 separate treatment of each spin leads to a natural ordering of the
105 determinants, and makes the evaluation of matrix elements in a
106 determinant basis very straightforward. However, it is is not
107 convenient for applications which need to manipulate all functions
108 with a given occupation of spatial orbtials (since these determinants
109 will be scattered throughout the CI vector) and should a fully
110 spin-adpated implementation be required very little code can be
111 reused.
112
113 \label{standardorder}
114
115 The graphical representations used below unite determinant and
116 spin-adapted approaches, and also preserve the simplicity of the
117 evaluation of matrix elements over determinants while providing the
118 option of using fully spin-adpated bases. For these reasons, let us
119 choose an order with
120 \begin{itemize}
121 \item all doubly occupied orbitals first (i.e., on the left) ordered
122 by increasing orbital index, and within each pair have the alpha
123 spin-orbital precede the beta spin-orbital, and
124 \item all singly occupied orbitals next, ordered by increasing orbital
125 index.
126 \end{itemize}
127 \begin{equation}
128 \underbrace{\phi_{1}(\RN{1})\alpha(1)\phi_{1}(\RN{2})\beta(2) \cdots
129 \phi_{d}(\RN{2d})\beta(2d)}_{\mbox{doubly occupied}}
130 \underbrace{\phi_{d+1}(\RN{2d+1})\sigma_{d+1}(2d+1) \cdots
131 \phi_{d+s}(\RN{n})\sigma_{n}(2d+s)}_{\mbox{singly occupied}}
132 \end{equation}
133 with $d$ doubly-occupied orbitals, and $s$ singly-occupied (or
134 open-shell) orbitals.
135 It is more convenient if we group the spatial and spin
136 functions separately,
137 \begin{eqnarray}
138 \Phi & = & {\cal A} \; \left[
139 \left(\phi_{1}(\RN{1})\phi_{1}(\RN{2}) \cdots \phi_{d}(\RN{2d})
140 \phi_{d+1}(\RN{2d+1}) \cdots \phi_{d+s}(\RN{n}) \right)\right. \\
141 & & \left.\left(\alpha(1)\beta(2) \cdots \beta(2d) \sigma_{d+1}(2d+1) \cdots
142 \sigma_{n}(2d+s)\right)\right]
143 \end{eqnarray}
144 This makes it clear that the {\em spin function depends only upon the
145 open shell orbitals}. This is because each doubly occupied orbital
146 always has an alpha and a beta spin function in the specified order
147 and thus a doubly occupied orbital may be placed anywhere since the
148 two functions will always be moved together (i.e, it will be an even
149 permutation) and therefore the sign of the determinant will be
150 unchanged. It is only ever necessary to consider the closed-shell
151 orbitals explicitly when computing matrix elements that involve these
152 indices, and then it suffices to consider any closed-shell pairs as
153 simply being two more open shells which happen to be numbered before
154 the `true' open shells.
155
156 It is also clear that the spatial functions (in the first set of
157 parentheses) and the spin functions may be managed separately. I will
158 adopt uppercase Roman letters for spatial orbital occupation patterns
159 ($|I\! >$) and the systematic construction of these is discussed below
160 in Section \ref{orbitalgraph}. The $\mu$'th determinantal or
161 primitive spin function for $s$ electrons and $S_z = m$ will be
162 denoted by $\theta^{(s)}_{m,\mu}$ (in the program the routines that
163 deal with primitive spin functions often begin with the letter `m'
164 because of the identification of $S_z = m$). If the Hamiltonian is
165 spin-free we only need to use functions with one value of $S_z$ and
166 the choice $S_z=S$ minimizes the dimension of the expansion space.
167
168 How many of these primitive spin functions functions are there? There
169 are $(\half s + m)$ alpha spin electrons and $(\half s -
170 m)$ beta spin electrons to be distributed in all possible ways amoung
171 $s$ orbitals. Thus, the number of primitive spin functions
172 (determinants) with $s$ open shells with given quantum number
173 $S_z=m$ is
174 \begin{equation}
175 d(s,m) = \frac{s!}{(\half s + m)! (\half s - m)!}
176 \end{equation}
177 By a similar argument, the dimension of a determinant full-CI
178 (ignoring spatial symmetry) with $n$ electrons in M orbitals and
179 $S_z=m$ is
180 \begin{equation}
181 D(M,n,m) = \nCr{M}{\half n + m}\nCr{M}{\half n - m}
182 \end{equation}
183
184 Our determinant, corresponding to the I'th orbital occupation which
185 has $s$ open shells, and the $\mu$'th primitive spin function for
186 the $s$ unpaired electrons coupled with $S_z=m$ is then finally
187 written as
188 \begin{eqnarray}
189 |I\mu\! > & = & {\cal A} \; |I\! > \Delta \theta^{(s)}_{m,\mu} , \\
190 |I\! > & = & \phi_{1}(\RN{1})\phi_{1}(\RN{2}) \cdots \phi_{d}(\RN{2d-1}\phi_{d}(\RN{2d})
191 \phi_{d+1}(\RN{2d+1}) \cdots \phi_{d+s}(\RN{n}) \\
192 \Delta & = &\alpha(1)\beta(2) \cdots \alpha(2d) \beta(2d) \\
193 \theta^{(s)}_{m,\mu} & = & \sigma_{d+1}(2d+1) \cdots
194 \sigma_{n}(2d+s)
195 \end{eqnarray}
196 where all of the closed-shell spin functions have been grouped into
197 $\Delta$ which never really needs to be considered.
198
199 \section{Graphical representation of primitive spin functions}
200
201 In this section we consider how the primitive spin functions are
202 numbered. We wish to find an ordering for all possible primitive spin
203 functions for $s$ unpaired electrons with $S_z = m$. A graphical
204 representation is very helpful. In Figure \ref{mgraph} the coupling
205 of the Z-component spin of each open-shell electron is represented
206 with a line. An upward line indicates alpha spin and a downward line
207 indicates beta spin. There are only two possible choices of spin, and
208 we arrange for the graph to begin at the origin and end at the desired
209 $S_z$ and number of electrons (in this case $S_z = 0$ and 8
210 electrons). Thus, the number of walks from left to right (or vice
211 versa) on this graph is equal to the total number of determinants.
212
213 \begin{figure}[htbp]
214
215 \center
216
217 \centerline{\psfig{figure=mspingraph.eps,angle=270}}
218 \caption{\label{mgraph} Graph of the primitive spin functions for 8
219 open-shell electrons coupled to $S_z=0$.}
220 \end{figure}
221
222 How many walks are there? Each node on the graph in Figure
223 \ref{mgraph} is labelled with its weight which is the number of
224 possible ways of arriving at that node. The weight of a node is the
225 sum of the weights of the (one or two) nodes that connect to it, and
226 the weight of the first node is one.
227
228 A walk on the graph is commonly represented with a plus sign
229 (\verb=+=) or number 1 for upward moves (alpha occupation) and a minus
230 sign (\verb=-=) or number 2 for downward moves (beta occupation). To
231 number each walk on the graph we must adopt some ordering and we use
232 the standard lexical order which places all functions coming from node
233 $(s-1,S_z+\half )$ before those from $(s-1,S_z-\half )$.
234 Thus, if when walking the graph from right to left we always stay as
235 high as possible we shall generate the lowest numbered walk. The
236 lexical ordering for all walks in Figure \ref{mgraph} is given in
237 Table \ref{mwalks}.
238
239 \begin{table}[htbp]
240
241 \center
242
243 \begin{tabular}{lc|lc|lc}
244 Index & Walk & Index & Walk & Index & Walk \\ \hline
245 1 & \verb=+ + + + - - - -= & 25 & \verb=- - + + + - + -= & 49 &
246 \verb=+ - - + - + - += \\
247 2 & \verb=+ + + - + - - -= & 26 & \verb=+ + - - - + + -= & 50 &
248 \verb=- + - + - + - += \\
249 3 & \verb=+ + - + + - - -= & 27 & \verb=+ - + - - + + -= & 51 &
250 \verb=- - + + - + - += \\
251 4 & \verb=+ - + + + - - -= & 28 & \verb=- + + - - + + -= & 52 &
252 \verb=+ - - - + + - += \\
253 5 & \verb=- + + + + - - -= & 29 & \verb=+ - - + - + + -= & 53 &
254 \verb=- + - - + + - += \\
255 6 & \verb=+ + + - - + - -= & 30 & \verb=- + - + - + + -= & 54 &
256 \verb=- - + - + + - += \\
257 7 & \verb=+ + - + - + - -= & 31 & \verb=- - + + - + + -= & 55 &
258 \verb=- - - + + + - += \\
259 8 & \verb=+ - + + - + - -= & 32 & \verb=+ - - - + + + -= & 56 &
260 \verb=+ + - - - - + += \\
261 9 & \verb=- + + + - + - -= & 33 & \verb=- + - - + + + -= & 57 &
262 \verb=+ - + - - - + += \\
263 10 & \verb=+ + - - + + - -= & 34 & \verb=- - + - + + + -= & 58 &
264 \verb=- + + - - - + += \\
265 11 & \verb=+ - + - + + - -= & 35 & \verb=- - - + + + + -= & 59 &
266 \verb=+ - - + - - + += \\
267 12 & \verb=- + + - + + - -= & 36 & \verb=+ + + - - - - += & 60 &
268 \verb=- + - + - - + += \\
269 13 & \verb=+ - - + + + - -= & 37 & \verb=+ + - + - - - += & 61 &
270 \verb=- - + + - - + += \\
271 14 & \verb=- + - + + + - -= & 38 & \verb=+ - + + - - - += & 62 &
272 \verb=+ - - - + - + += \\
273 15 & \verb=- - + + + + - -= & 39 & \verb=- + + + - - - += & 63 &
274 \verb=- + - - + - + += \\
275 16 & \verb=+ + + - - - + -= & 40 & \verb=+ + - - + - - += & 64 &
276 \verb=- - + - + - + += \\
277 17 & \verb=+ + - + - - + -= & 41 & \verb=+ - + - + - - += & 65 &
278 \verb=- - - + + - + += \\
279 18 & \verb=+ - + + - - + -= & 42 & \verb=- + + - + - - += & 66 &
280 \verb=+ - - - - + + += \\
281 19 & \verb=- + + + - - + -= & 43 & \verb=+ - - + + - - += & 67 &
282 \verb=- + - - - + + += \\
283 20 & \verb=+ + - - + - + -= & 44 & \verb=- + - + + - - += & 68 &
284 \verb=- - + - - + + += \\
285 21 & \verb=+ - + - + - + -= & 45 & \verb=- - + + + - - += & 69 &
286 \verb=- - - + - + + += \\
287 22 & \verb=- + + - + - + -= & 46 & \verb=+ + - - - + - += & 70 &
288 \verb=- - - - + + + += \\
289 23 & \verb=+ - - + + - + -= & 47 & \verb=+ - + - - + - += & \\
290 24 & \verb=- + - + + - + -= & 48 & \verb=- + + - - + - += & \\ \hline
291 \end{tabular}
292
293 \caption{\label{mwalks} Lexical ordering of walks on the primtive spin
294 graph in Figure 1.}
295 \end{table}
296
297 Since we have all possible walks on the graph, then switching any two
298 orbitals will just generate another walk on the graph.
299
300 \section{Graphical representation of CSF bases}
301
302 Internally the program uses determinants, but provides the capability
303 of transforming to the Yamanouchi-Kotani \cite{kotani} genealogical
304 spin basis with conventional lexical ordering and numbering of
305 electrons (see Pauncz \cite{pauncz}). This is the same as the
306 standard Young orthogonal representation which is also equivalent to
307 the Gelfand-Tsetlin basis of the unitary group approach.
308
309 The branching diagram (Figure \ref{sgraph}) depicts the construction
310 of a spin-adapted basis by the coupling of electronic spins.
311
312 \begin{figure}[htbp]
313
314 \center
315
316 \centerline{\psfig{figure=spingraph.eps,angle=270}}
317 \caption{\label{sgraph} Branching-diagram or spin-coupling graph for 8
318 open-shell electrons coupled to a singlet.}
319 \end{figure}
320
321 The spin-adpated basis is formed by using standard angular momentum
322 coupling methods. Electrons are again added one at a time, but now
323 the total angular momentma are coupled, rather than just the $S_z$
324 component. If some intermediate node has spin $S$, then adding an
325 alpha spin or beta spin electron will result in $S\pm\half $, but
326 we also have the constraint that $S \geq 0$. Thus, all walks on the
327 spin-adpated graph must be above the horizontal axis, in contrast to
328 the graph for primitive spin functions ($-S \leq S_z \leq S$). It can
329 again be seen that walks on the graph represent all possible spin
330 functions and consideration of the spin-coupling shows that the
331 resulting basis is orthonormal.
332
333 How many spin adapted functions are there? The determinants for given
334 $s$ and $S_z$ will form a complete basis for $S=S_z, S_z+1,\ldots$, and
335 thus
336 \begin{equation}
337 d(s,S) = f(s,S) + f(s,S+1) + \cdots + f(s,S_{max})
338 \end{equation}
339 Therefore, the number of spin-adpated functions for $s$ open-shell
340 electrons coupled to spin $S$ is
341 \begin{eqnarray}
342 f(s,S) & = & d(s,S) - d(s,S+1) \\
343 & = & d(s,S) \frac{(2S + 1)}{(\half s + S + 1)} \\
344 & = & \nCr{s+1}{\half s - S}\frac{(2S + 1)}{(s+1)}
345 \end{eqnarray}
346
347 The same argument may be invoked to demonstrate that the dimension
348 of a spin-adpated full-CI for $n$ electrons in $M$ orbitals for total
349 spin $S$, is
350 \begin{eqnarray}
351 F(M,n,S) & = & D(M,n,S) - D(M,n,S+1) \\
352 & = & D(M,n,S) \frac{(M+1)(2S+1)}{(\half n + S + 1)(M-\half n +S+1)}
353 \end{eqnarray}
354
355 The FCI program provides routines (see Section \ref{spinad1}) to
356 transform between the determinant and CSF spin bases for a given
357 open-shell occupation. This follows the approach of Duch
358 \cite{duchspinad} but is readily constructed from the detailed
359 descriptions of the coupling in the books of Pauncz (e.g., see from
360 page 96 of \cite{paunczsym}).
361
362 \section{Graphical representation of orbital occupations}
363 \label{orbitalgraph}
364
365 Orbital occupations may be 0, 1, or 2 (empty, singly-, or
366 doubly-occupied) and are represented by walks on a 3-way graph
367 \cite{duchsga,duchfci}. Since we are doing a full-CI we need all
368 possible walks. Figure \ref{ograph} is an orbital graph for a full-CI
369 with 8-electrons in 8-orbitals without use of spatial symmetry.
370 Again, each node can be assigned a weight which is the sum of the
371 weights of the nodes that connect to it from above. The weight of the
372 head (top node) is 1 and the weight of the tail (bottom node) is the
373 number of walks.
374
375
376 The lexical ordering of orbital walks is such that in traversing the
377 graph from bottom to top walks the rightmost arcs have lowest lexical
378 weight (the first and last twenty four walks on the graph in Figure
379 \ref{orbitalgraph} are given in Table \ref{owalks}).
380
381 \begin{figure}[htbp]
382
383 \center
384
385 \centerline{\psfig{figure=orbitalgraph.eps,angle=270}}
386 \caption{\label{ograph} Orbital occupation graph for a full-CI with 8
387 electrons in eight orbitals.}
388 \end{figure}
389
390 \begin{table}[htbp]
391
392 \center
393
394 \begin{tabular}{lc|lc}
395 Index & Walk & Index & Walk \\ \hline
396 1 & 2 2 2 2 0 0 0 0 &1084 & 0 0 2 0 1 1 2 2 \\
397 2 & 2 2 2 1 1 0 0 0 &1085 & 1 0 0 1 1 1 2 2 \\
398 3 & 2 2 1 2 1 0 0 0 &1086 & 0 1 0 1 1 1 2 2 \\
399 4 & 2 1 2 2 1 0 0 0 &1087 & 0 0 1 1 1 1 2 2 \\
400 5 & 1 2 2 2 1 0 0 0 &1088 & 0 0 0 2 1 1 2 2 \\
401 6 & 2 2 2 0 2 0 0 0 &1089 & 1 0 0 0 2 1 2 2 \\
402 7 & 2 2 1 1 2 0 0 0 &1090 & 0 1 0 0 2 1 2 2 \\
403 8 & 2 1 2 1 2 0 0 0 &1091 & 0 0 1 0 2 1 2 2 \\
404 9 & 1 2 2 1 2 0 0 0 &1092 & 0 0 0 1 2 1 2 2 \\
405 10 & 2 2 0 2 2 0 0 0 &1093 & 2 0 0 0 0 2 2 2 \\
406 11 & 2 1 1 2 2 0 0 0 &1094 & 1 1 0 0 0 2 2 2 \\
407 12 & 1 2 1 2 2 0 0 0 &1095 & 0 2 0 0 0 2 2 2 \\
408 13 & 2 0 2 2 2 0 0 0 &1096 & 1 0 1 0 0 2 2 2 \\
409 14 & 1 1 2 2 2 0 0 0 &1097 & 0 1 1 0 0 2 2 2 \\
410 15 & 0 2 2 2 2 0 0 0 &1098 & 0 0 2 0 0 2 2 2 \\
411 16 & 2 2 2 1 0 1 0 0 &1099 & 1 0 0 1 0 2 2 2 \\
412 17 & 2 2 1 2 0 1 0 0 &1100 & 0 1 0 1 0 2 2 2 \\
413 18 & 2 1 2 2 0 1 0 0 &1101 & 0 0 1 1 0 2 2 2 \\
414 19 & 1 2 2 2 0 1 0 0 &1102 & 0 0 0 2 0 2 2 2 \\
415 20 & 2 2 2 0 1 1 0 0 &1103 & 1 0 0 0 1 2 2 2 \\
416 21 & 2 2 1 1 1 1 0 0 &1104 & 0 1 0 0 1 2 2 2 \\
417 22 & 2 1 2 1 1 1 0 0 &1105 & 0 0 1 0 1 2 2 2 \\
418 23 & 1 2 2 1 1 1 0 0 &1106 & 0 0 0 1 1 2 2 2 \\
419 24 & 2 2 0 2 1 1 0 0 &1107 & 0 0 0 0 2 2 2 2 \\ \hline
420 \end{tabular}
421
422 \caption{\label{owalks} The first and last twenty-four lexically
423 ordered walks on an 8-electron 8-orbital full-CI orbital occupation graph.}
424 \end{table}
425
426 Spatial symmetry is in the code in a rudimentary, but useful, fashion.
427 The walks are ordered as if there is no symmetry (c.f., Table
428 \ref{owalks}) and the symmetry of each walk is simply computed as the
429 direct product of the symmetry of the singly-occupied orbitals
430 (directly available from the routine \verb+fci_owalk_info()+, Section
431 \ref{sec:fciowalkinfo}). Only walks/occupations of the desired
432 symmetry are included in the CI vector (Section \ref{sec:ciindex}).
433 This facilitates use of symmetry to reduce the storage required for
434 the CI vector, and also the computation of matrix elements for
435 perturbation methods. It also makes it easy to use the routines in
436 instances when you want to sum over all intermediate states regardless
437 of symmetry. However, the walks of a specific symmetry are not
438 grouped together and symmetry is not presently used to reduce the
439 expense of the CI eigenvalue problem.
440
441 An alternative approach, which I've used in other programs,
442 is to modify the orbital graph by splitting each node so
443 that there is one for each irreducible representation. The symmetry
444 of an orbital must be taken into account when singly occupying it so
445 that the node of the correct occupation and symmetry is connected to
446 on the next level. This was, I think, first introduced by Shavitt
447 \cite{shavittguga,shavittguga2} in the 4-way graph (or distinct row
448 table, DRT) of the graphical unitary group approach (GUGA).
449
450 \section{Indexing the CI vector}
451 \label{sec:ciindex}
452
453 The CI vector looks like a two-dimensional array, $C_{\nu I}$ with the
454 outermost index running over orbital occupations ($I$) in lexical
455 order, and the innermost index ($\nu$) over possible spin functions
456 for that orbital occupation, again in lexical order. Since the number
457 of spin functions varies with the number of singly occupied orbitals
458 in $I$, the CI vector is stored as a one-dimensional vector with an
459 index vector of dimension the number of orbital walks to point to the
460 beginning of the coefficients for a given walk $I$ (see the routine
461 \verb+fci_owalk_info()+, Section \ref{sec:fciowalkinfo}). Note that
462 only coefficients of the correct symmetry are stored and therefore the
463 index into the CI vector is only meaningful for these orbital walks
464 and care must be taken to ensure the correct symmetry before trying to
465 use an index into the CI vector.
466
467 An interesting variation would be to group together within the CI
468 vector all orbital occupations with the same number of singly-occupied
469 orbitals. Within each group the number of spin functions is now the
470 same and the CI vector may be treated as a two-dimensional array.
471
472 \section{More details on the graphical representations}
473
474 \subsection{Primitive spin graphs}
475
476 Primitive spin graphs are slightly easier since they have at most two
477 arcs from any node. Nodes are labelled by the number of singly
478 occupied orbitals ($s$) and the intermediate $S_z=m$. The weight of a
479 node $d(s,m)=d^s_m$ is then
480 \begin{equation}
481 d^s_m = d^{s-1}_{m-\half} + d^{s-1}_{m+\half} \mbox{\ with\ } d^0_0 =
482 1 \label{spinnodeweight}
483 \end{equation}
484 in which nodes with no connecting arcs have zero weight.
485 The lexical ordering of walks on a graph is established by assigning a
486 weight to each arc on the graph. The arcs weights are labelled as
487 follows
488 \begin{eqnarray}
489 Y^{s-}_m & \mbox{connects} & (s,m) \rightarrow (s+1,m-\half ) \\
490 Y^{s+}_m & \mbox{connects} & (s,m) \rightarrow (s+1,m+\half )
491 \end{eqnarray}
492
493 \begin{figure}[htbp]
494
495 \center
496
497 \centerline{\psfig{figure=spinarcs.eps,angle=270}}
498 \caption{\label{spinarcs} The two arcs coming into node $(s,m)$ on a
499 primtive spin graph, and their arc weights.}
500 \end{figure}
501
502 The weight ($w_{\sigma}$) or lexical index of a walk
503 ($\{\sigma_j:j=1,s\}$, c.f., Table \ref{mwalks}) is just
504 \begin{equation}
505 w_{\sigma} = 1 + \sum_{j=1}^{s} Y_{m_j}^{s_j \sigma_j} \label{spinwalkweight}
506 \end{equation}
507 where $s_j$ and $m_j$ are the intermediate values of the number of
508 electrons and $S_z$ at nodes along the walk.
509
510 An arc is assigned a weight equal to the number of walks from
511 the current node that have lower index. The standard lexical ordering
512 corresponds to walking from right to left with the upward arc (right
513 to left!) being of lower index. Thus, considering the two arcs going
514 from right to left from node $(s,m)$
515 (see Figure \ref{spinarcs}) the lexical ordering is
516 accomplished by the following assignments
517 \begin{eqnarray}
518 Y^{(s-1)-}_{m+\half} & = & 0 \nonumber \\
519 Y^{s+}_m & = & d_{s-1}^{m+\half} \label{spinarcweights}
520 \end{eqnarray}
521 For computational convenience, an arc that does not exist is assigned
522 zero weight. There is no need for a primtive (or spin-adapted) spin
523 graph to have separate node and arc weight tables, however, the
524 current code does do this. They are small so the additional memory is
525 not an issue.
526
527 \subsection{Orbital graphs}
528
529 Nodes on an orbital graph are labelled by the level ($l$), which
530 corresponds the orbital being occupied by arcs going down, and the
531 number of electrons $n$. When spatial symmetry is introduced there
532 will be an additional index for each irreducible representation. The
533 weight ($k^l_n = k(l,n)$) of each node is simply
534 \begin{equation}
535 k^l_n = k^{l-1}_{n-2} + k^{l-1}_{n-1} + k^{l-1}_n \label{orbnodeweight}
536 \end{equation}
537 where it is assumed that nodes with no connecting arcs have zero weight.
538
539 \begin{figure}[htbp]
540
541 \center
542
543 \centerline{\psfig{figure=orbitalarcs.eps,angle=270}}
544 \caption{\label{orbitalarcs} The three arcs, and their weights,
545 coming into node $(l,n)$ on an orbital occupation graph.}
546 \end{figure}
547
548 The three possible arcs descending from a node are (see Figure
549 \ref{orbitalarcs})
550 \begin{eqnarray}
551 Z^{l,0}_{n} & \mbox{connects} & (l,n) \rightarrow (l+1,n) \\
552 Z^{l,1}_{n} & \mbox{connects} & (l,n) \rightarrow (l+1,n+1) \\
553 Z^{l,2}_{n} & \mbox{connects} & (l,n) \rightarrow (l+1,n+2)
554 \end{eqnarray}
555 and again the weight ($w_z$) of an orbital walk ($\{z: z_l,l=1,M\}$, for
556 $M$ orbitals, $z_l=0,1,2$) or occupation pattern, is simply
557 \begin{equation}
558 w_z = 1 + \sum_{l=1}^{M} Z^{l,z_l}_{n_l} \label{orbwalkweight}
559 \end{equation}
560 where $n_l$ is the intermediate number of electrons at each node in
561 the walk. Note that in the full-CI program the arcs $Z^{l,j}_n,
562 j=0,1,2$ are actually indexed with $j=1,2,3$ for historical reasons.
563
564 The lexical ordering of orbital walks is such that in traversing the
565 graph from bottom to top walks the rightmost arcs have lowest lexical
566 weight (the first and last twenty four walks on the graph in Figure
567 \ref{orbitalgraph} are given in Table \ref{owalks}).
568 Thus, the weight of an upward bound arc should be equal to the number
569 of possible walks that traverse other arcs from the same node that are
570 to the right of the arc of interest. Considering again the three arcs
571 going up from node $(l,n)$ (Figure \ref{orbitalarcs})
572 \begin{equation}
573 Z^{l-1,j}_{n-j} = Z^{l-1,j-1}_{n-j+1} + k^{l-1}_{n-j+1} \mbox{\ with\ }
574 Z^{l-1,0}_n = 0 \label{orbarcweights}
575 \end{equation}
576 where $k^{l-1}_{n-j+1}$ (Equation \ref{orbnodeweight}) is the number of
577 walks coming down from node $(l-1,n-j+1)$. Again, for computational
578 convenience, arcs and nodes that do not exist are assigned zero
579 weight.
580
581 Aside: Multiple tails can be accomodated on the same graph by setting
582 the weight of $Z^{M,0}_n$ to be the sum of the weights of other tails
583 to the right.
584
585 \subsection{Constructing the weights and walking the graphs}
586
587 The node weights are readily formed by traversing the graphs from head
588 to tail (left to right for the spin graphs, top to bottom for the
589 orbital graphs) using the recursive formulae for the node weights
590 (Equations \ref{orbnodeweight} and \ref{spinnodeweight}).
591
592 The arc weights are then determined by traversing the graphs from tail
593 to head (right to left for the spin graphs, bottom to top for the
594 orbital graphs) using the recursive formulae for the arc weights
595 (Equations \ref{spinarcweights} and \ref{orbarcweights}).
596
597 Given a walk on a graph (i.e., either a spin or orbital occupation
598 pattern) the lexical weight is readily computed from the arc weights
599 (Equations \ref{spinwalkweight} and \ref{orbwalkweight}). This
600 requires $O(N)$ array references and integer additions (where $N$ is
601 the number of open shells or the number of orbitals for spin and
602 orbital graphs respectively).
603
604 Determining the occcupation from the lexical weight is only slightly
605 harder. Starting from the tail of the graph we accumulate the weight
606 of a trial walk (initialized to 1), and at each node we take the
607 highest weight arc (i.e., the lowest spin arc, or the leftmost orbital
608 arc) that is consistent with the incremented walk weight being less
609 than or equal to the weight of the walk we are seeking. This process
610 requires $O(N)$ comparisons as well as $O(N)$ array look-ups and
611 integer additions.
612
613 \section{Matrix elements of orbital replacement operators}
614
615 In the determinant basis it is easy to compute matrix elements of
616 spin-dependent operators, however, I presently restrict attention to
617 spin-adapted operators (e.g., $E_{ij}$) which act as spatial orbital
618 replacement operators. By doing this the formalism for evaluating
619 matrix elements over both CSF and determinants is exactly the same (I
620 think it can be made the same even in the case of spin-dependent
621 operators but only with an extended notation).
622
623 \begin{enumerate}
624 \item Note that an orbital replacement operator commutes with
625 permutations that act on the electrons --- the labels are independent.
626
627 \item Let $\hat{Q}$ be an orbital replacement operator and let $|K\! >$
628 and $|I\! >$ be orbital configurations in standard order (Section
629 \ref{standardorder}) such that
630 \begin{eqnarray}
631 |K\! > & = & Q |K^Q\! > = Q \hat{Q} |I\! > \mbox{, or}
632 \label{qik1} \\
633 \hat{Q} \; |I \! > & = & Q^{-1} |K \! > \label{qik}
634 \end{eqnarray}
635 where $|K^Q\! >$ is an orbital configuration in {\em non-standard}
636 order that is produced by the action of $\hat{Q}$ on $|I\! >$. $Q$ is
637 the electronic permutation that returns $|K^Q\! >$ to standard
638 occupation order. This is the line-up permutation (or the inverse of
639 it depending on your perspective).
640
641 \item Recall that a determinant or CSF is written
642 \begin{equation}
643 |I \lambda\! > = {\cal A} \; |I\! > \Theta_{\lambda} \label{csfdefn}
644 \end{equation}
645
646 \item Also recall these properties of the antisymmetrizer
647 \begin{eqnarray}
648 {\cal A} & = & \frac{1}{\sqrt{n!}} \sum_P (-1)^P P \\
649 & = & {\cal A}^{\dagger} \\
650 {\cal A}^2 & = & \sqrt{n!} {\cal A} \\
651 PA & = & AP = (-1)^P A \label{paap}
652 \end{eqnarray}
653
654 \item The action of $\hat{Q}$ on a determinant or CSF is then formed
655 as follows
656 \begin{eqnarray}
657 \hat{Q} |I \lambda\! >
658 & = & \hat{Q} \; {\cal A} \; |I\! > \Theta_{\lambda} \mbox{, defined
659 by \ref{csfdefn}} \\
660 & = & {\cal A} \; \hat{Q} \; |I\! > \Theta_{\lambda} \mbox{, from
661 independence of orbital and electronic labels} \\
662 & = & {\cal A} \; \left( \hat{Q} \; |I\! > \right) \Theta_{\lambda}
663 \mbox{, since only I contains orbital labels} \\
664 & = & {\cal A} \; \left( Q^{-1} \; |K\! > \right) \Theta_{\lambda}
665 \mbox{, using \ref{qik}} \\
666 & = & \left[ {\cal A} \; (-1)^Q Q \right] \left( Q^{-1} \; |K\! >
667 \right) \Theta_{\lambda} \mbox{, using \ref{paap}} \\
668 & = & {\cal A} \; (- 1)^Q |K\! > \left( Q \; \Theta_{\lambda} \right)
669 \\
670 & = & {\cal A} \; |K\! > \left( (- 1)^Q \sum_{\mu} \Theta_{\mu}
671 U_{\mu \lambda}(Q) \right) \\
672 & = & (-1)^Q \sum_{\mu} |K \mu\! > U_{\mu \lambda}(Q)
673 \end{eqnarray}
674 where $U_{\mu \lambda}(Q)$ is an element of the representation matrix
675 of the permutation $Q$ in the spin-function basis. The phase-factor
676 may also be included in $U$ in which case it is referred to as the
677 contra-gradient representation.
678
679 \item Using the above results we can readily obtain the value for the
680 matrix element
681 \begin{eqnarray}
682 <\! K\nu | \hat{Q} | I \lambda\! > & = & (-1)^Q \sum_{\mu}
683 <\! K \nu | K \mu \! > U_{\mu \lambda}(Q) \label{lineupeqn} \\
684 & = & (-1)^Q U_{\nu \lambda}(Q)
685 \end{eqnarray}
686 In Equation \ref{lineupeqn} only one term survives because of the
687 orthogonality of the spatial orbitals and the chosen spin function
688 bases (both primitive and spin adapted).
689 \end{enumerate}
690
691 What line-up permutations ($Q$) are of interest? Consider $\hat{Q} =
692 E_{ij}$ where orbital $j$ is singly occupied in $|I\! >$ ($n_j^I = 0$)
693 and orbital $i$ is unoccupied ($n_i^I=0$). This simply replaces
694 orbital label $j$ with $i$. Let $\overline{i}$ and $\overline{j}$ be
695 the correct standard position of orbitals $i$ and $j$ respectively
696 amoung the singly occupied orbitals (which should be occupied in
697 increasing order). Furthermore, let us assume that $i < j$. Then,
698 the permutation of the (singly occupied) electronic coordinates that
699 restores the correct ordering of the occupation is the cyclic
700 permutation $(\overline{i} \ldots \overline{j})$. The situation for
701 $j$ doubly occupied, or $i$ singly occupied is similar, but we defer
702 discussion of this since additional simplifications are possible.
703
704 A detailed example may help. Considering just the singly occupied
705 orbitals and with
706 \begin{equation}
707 |I \! > = \phi_1(1) \phi_3(2) \phi_4(3) \phi_5(4) \phi_6(5)
708 \end{equation}
709 then, we see that
710 \begin{eqnarray}
711 E_{25} |I \! > & = & \phi_1(1) \phi_3(2) \phi_4(3) \phi_2(4)
712 \phi_6(6) \\
713 & = & \phi_1(1) \phi_2(4) \phi_3(2) \phi_4(3) \phi_6(5)
714 \end{eqnarray}
715 (which is denoted $K^Q$ in Equation \ref{qik1}). But the standard
716 order of occupation should be
717 \begin{equation}
718 |K \! > = \phi_1(1) \phi_2(2) \phi_3(3) \phi_4(4) \phi_6(5)
719 \end{equation}
720 and the permutation of the {\em electronic} labels that accomplishes
721 this is the cyclic permutation $(2 3 4) = (2 3)(3 4)$. This maps
722 electron 2 into electron 3, electron 3 into electron 4, and electron 4
723 back into electron 2.
724 \begin{equation}
725 (2 3 4) \left[ \phi_1(1) \phi_2(4) \phi_3(2) \phi_4(3) \phi_6(5)
726 \right] = \phi_1(1) \phi_2(2) \phi_3(3) \phi_4(4) \phi_6(5)
727 \end{equation}
728 The correct position of orbital 5 amoung the singly occupied orbitals
729 in $I$ is $\overline{j}=4$ and that of orbital 2 is $\overline{i}=2$.
730
731 \subsection{Computing matrix elements}
732
733 In the primitive spin or determinant basis, there will be just one
734 non-zero element in each row or column of the representation matrix
735 ($U_{\mu \lambda}(Q)$) for any permutation, whereas the representation
736 matrices for spin adpated bases will be rather dense. This fact may
737 be exploited (Duch \cite{duchspinad}) by just storing, in what Duch
738 named Primitive Spin Function Transformation Tables, the index to which
739 each primitive spin function transforms under the action of all cyclic
740 permutations and the corresponding phase factor.
741
742 For small FCI calculations this is very effective and it is what was
743 implemented in the original code. However, larger calculations have
744 too much data to hold since the number of entries is $5*(s+1)^2d^s_m$
745 which becomes very large for more than 10 or 12 active orbitals (the
746 factor of 5 arises from the various occupation cases). Duch
747 recommended various alternatives, but following Knowles and Werner
748 \cite{knowleseai}, and in the spirit of the $N-2$ particle subspace
749 projection of Zarrabian et al \cite{zarrabian,harrison}, we can use the
750 following factorization
751 \begin{equation}
752 E_{ij} = E_{ia}E_{aj}
753 \end{equation}
754 where $a$ is a ficticious orbital of index higher than any other
755 orbital. This is equivalent to factorizing the cyclic permutation as
756 \begin{equation}
757 (\overline{i} \ldots \overline{j}) = (\overline{i} \ldots s)(s \ldots
758 \overline{j}) \mbox{\ for\ } i < j
759 \end{equation}
760 where, again, $s$ is the number of open shell electrons. It is also
761 akin to the action of an annihilation operator but rather than keeping
762 track of the $s-1$ electron states we just put the electron into a
763 fictitious orbital. With this factorization there are only two
764 occupation cases to consider (with a total of three entries) since $a$
765 is always empty and there is a total of only $3(s+1)d^s_m$ entries to
766 be stored which is tractable for very large numbers of open shells.
767
768 The code constructs just the transformations associated with $<\!
769 K\mu|Eaj|J\nu\! >$ for $n_j=1,2$. This is done as follows, initially
770 for $n_j = 1$.
771 \begin{enumerate}
772 \item Loop thru primitive spin functions $\nu$ for $s$ open shell
773 electrons and obtain the corresponding occupation pattern (by calling
774 \verb+fci_find_mocc+).
775
776 \item Loop thru $j=1,s$ corresponding to the cycles $(s \ldots j)$ for
777 $j=1,s$ and apply it to the occputation pattern.
778
779 \item Determine the lexical index of the generated occupation (by
780 calling \verb+fci_find_mweight+). Store this multiplied by the parity
781 of the permutation in $T(\nu,j,1)$.
782 \end{enumerate}
783
784 For $n_j=2$ the situation is only slightly more complex since we will
785 obtain two $s+2$ electron occupations from breaking the alpha--beta pair.
786 \begin{enumerate}
787 \item Loop thru primitive spin functions $\nu$ for $s$ open shell
788 electrons, and obtain the corresponding occupation pattern (by calling
789 \verb+fci_find_mocc+).
790
791 \item Loop thru $j=1,s+1$ corresponding to the position amoung the
792 singly occupied orbitals of the new orbital.
793
794 \item First excite the alpha spin electron by constructing an $s+2$
795 electron spin function by appending ``\verb=+='' to the $s$ electron
796 spin function $\nu$ and inserting a ``\verb=-='' immediately before
797 position $j$. Determine the new $s+2$ lexical walk index and store
798 it times the phase of the permutatation (the parity of $(j \ldots
799 1)(s+2 \ldots 1)$ is $(-1)^{s+j}$) in $T^{s,2}_{\nu,j}$.
800
801 \item Next excite the beta spin electron by constructing an $s+2$
802 electron spin function by appending ``\verb=-='' to the $s$ electron
803 spin function $\nu$ and inserting a ``\verb=+='' immediately before
804 position $j$. Determine the new $s+2$ electron walk index and store
805 it with the negative of the previous parity (since we swapped the
806 first two electrons and the actual permutation is $(j \ldots
807 1)(s+2 \ldots 1)(1 2)$) in $T^{s,3}_{\nu,j}$.
808 \end{enumerate}
809
810 Finally, some logic is eliminated from the inner loop if instead of
811 storing the phase directly in the table as recommended by Duch
812 \cite{duchspinad}, we store it separately. This does not require a
813 lot of memory since it is independent of the spin function index.
814
815 \section{Density matrix operators}
816
817 Arbitrary-rank density matrix operators are very readily constructed
818 from the $E_{ai}$ operators \cite{knowleseai} since
819 \begin{equation}
820 E_{pq,rs,tu,\ldots} =
821 E_{pa}E_{rb}E_{tc}\ldots E_{cu}E_{bs}E_{aq}
822 \end{equation}
823 where the fictitious orbitals are regarded as being ordered
824 $\cdots>c>b>a$. This looks very much like the standard normal ordered
825 form of the operator in terms of annihilation/creation operators. In
826 applying this expression in practice the following factorization has
827 several important properties in a determinant basis (with implied
828 summation over the repeated indices)
829 \begin{equation}
830 < \! J\nu |E_{pq,rs,tu,\ldots}| I \omega \! > =
831 < \! J\nu |E_{pa}E_{rb}E_{tc}\ldots |N\mu \! >
832 < \! N\mu |\ldots E_{cu}E_{bs}E_{aq}|I\omega \! > \\
833 \end{equation}
834 \begin{enumerate}
835 \item If the operators $E_{aq}$ etc. act only on open-shell electrons
836 then the number of open-shell electrons is unchanged, and the mapping
837 from $\omega$ to $\mu$ is one-to-one and dense (a permutation).
838 \item If the operators $E_{aq}$ etc. break a spin pair then the number
839 of electrons is increased by two and the mapping from $\omega$ to
840 $\mu$ is one-to-two. There is some sparsity (less than 50\% for
841 singlets) in the increased space since some spin couplings cannot be
842 generated from the broken spin pair. For instance, examination of
843 Figure \ref{mgraph} shows that six open-shell electrons give rise to
844 20 determinants, which if a closed-shell spin pair is broken, can only
845 give rise to 40 determinants. However, there are 70 determinants for
846 8 open shells.
847 \end{enumerate}
848
849 The coupling coefficient generation routines then work in a very
850 straightforward fashion, working from the outside to the middle, and
851 then multiplying the two halves together. Each application of an
852 operator ($E_{aq}$) results in a mapping from the spin functions in
853 the input (ket) to those in the output (bra) indices and some
854 associated phases. These are specified by the occupation of the
855 orbital that is having an electron removed ($q$ in this instance), and
856 by the position of this orbital in the standard ordering of singly
857 occupied orbitals (if this is orbital $q$ its position amoung the
858 singly occupied is referred to as $\overline{q}$ or \verb+qbar+). So
859 some book keeping is necessary to keep track of this information. The
860 routines are heavily commented and coded in a stylized fashion so they
861 should be self-explanatory.
862
863 \section{Application Program Interface --- API}
864
865 The following routines will be augmented so that they provide access
866 to all of the necessary information to compute matrix elements,
867 manipulate walks on the orbital and spin graphs, and convert between
868 determinant and CSF bases.
869
870 Obviously, an application that needs FCI information in its innermost
871 loop may need to access that information directly from the FCI common
872 blocks for reason of efficiency. However, since the common blocks
873 will need to change in order to accomodate orbital symmetry and
874 modification of the algorithm to compute the coupling coefficients, it
875 is strongly recommended that the API be used (or extended) wherever
876 possible.
877
878 \subsection{Setting-up and solving a full-CI}
879
880 \subsubsection{{\tt fci\_setup}}
881
882 \begin{verbatim}
883 subroutine fci_setup(multiplicity, nactive, nelectrons,
884 & orbsyms, symstate,
885 & norbitalconfig, ndeterminants, nconfigurations,
886 & norbconfignosym)
887 integer multiplicity ! [input] Spin multiplicity
888 integer nactive ! [input] No. of active orbitals
889 integer nelectrons ! [input] No. of active electrons
890 integer orbsyms(nactive) ! [input] Symmetry of orbitals (1...8)
891 integer symstate ! [input] Desired symmetry of state
892 integer norbitalconfig ! [output] No. of orb. conf. WITH symmetry
893 integer ndeterminants ! [output] No. of determinants in FCI
894 integer nconfigurations ! [output] No. of configurations in FCI
895 integer norbconfignosym ! [output] No. of orb. conf. WITHOUT symmetry
896 \end{verbatim}
897 This routine must be called before anythine else to initialize the
898 internal FCI data structures. The determinant CI vector using
899 symmetry will be of length \verb+ndeterminants+ (equivalent to
900 \verb+nconfigurations+ CSF).
901
902 \subsubsection{{\tt fci\_solve}}
903 \label{sec:fcisolve}
904 \begin{verbatim}
905 subroutine fci_solvenew(nroot, thresh, maxvec, ecore, h, g,
906 & work, lenwrk, roots, evecfilename, diagfilename)
907 integer nroot ! [input] No. of roots to find
908 double precision thresh ! [input] Threshold for residual norm
909 integer maxvec ! [input] Davidson subspace dim PER ROOT
910 double precision ecore ! [input] Nuclear repulsion+frozen core
911 double precision h(nacttr) ! [input] h(ij) = h_{ij}
912 double precision g(nacttr,nacttr) ! [input] g(ij,kl) = (ij|kl)
913 integer lenwrk ! [input] Size of work space
914 double precision work(lenwrk) ! [scratch] Work space
915 double precision roots(nroot) ! [output] Returns the eigenvalues
916 character*(*) evecfilename ! [input] Name of file for eigen vectors
917 character*(*) diagfilename ! [input] Name of file for diagonals
918 \end{verbatim}
919
920 Solve the CI to the requested accuracy. Currently uses determinants
921 but is readily extended to also accomodate CSF. The eigenvalues are
922 returned in \verb+roots+. The eigenvectors are returned in file
923 \verb+evecfilename+, and the diagonal elements of the Hamiltonian are
924 returned in \verb+diagfilename+. The eigenvectors and diagonal
925 elements may be read using the routine \verb+fci_readvectors()+
926 (Section \ref{sec:fcireadvectors}).
927
928 The input integrals are stored as
929 \verb+h(ij)+=$h_{ij}$ and \verb+g(ij,kl)=$(ij|kl)$, with $i \geq j$,
930 $k \geq l$, \verb+ij+=$i(i-1)/2$, and \verb+kl+=$k(k-1)/2+l$. Have a
931 look at \verb+fci_load.F+ to see how an ASCII list of integrals are
932 read in an inserted into these arrays in the test program.
933
934 The minimum amount of workspace required (\verb+lenwrk+)is independent
935 of the number of roots, and must exceed 2*\verb+ndeterminants+. The
936 more memory the better, but 2*\verb+ndeterminants++500000 will
937 probably always be enough.
938
939 Also, there is currently no possibility of restart, and the lowest
940 diagonal guess is always used.
941
942 \subsubsection{{\tt fci\_readvectors}}
943 \label{sec:fcireadvectors}
944 \begin{verbatim}
945 subroutine fci_readevectors(ndets, nvec, v, filename)
946 integer ndets ! [input] Vector length
947 integer nvec ! [input] No.
948 double precision v(ndets,nvec)
949 character*(*) filename
950 \end{verbatim}
951
952 The FCI package uses word-addressable random access files that cannot
953 be accessed using standard Fortran I/O operations. This routine
954 enables the eigen-vectors and diagonal elements to be read from disk
955 by specifying the appropriate filename after \verb+fci_solve()+ has
956 sucessfully completed. To read the eigenvectors, specify \verb+nvec+
957 as \verb+nroot+. To read the diagonal elements, specify \verb+nvec+
958 as one.
959
960 \subsection{Inquiring about occupations and dimensions}
961
962 \subsubsection{{\tt fci\_ofind\_occ}}
963 \begin{verbatim}
964 subroutine fci_ofind_occ(iwalk,iocc)
965 c
966 c find the orbital occupation of walk with lexical index iwalk
967 c
968 integer iwalk ! [input]
969 integer nel ! [input]
970 integer iocc(*) ! [output]
971 \end{verbatim}
972
973 \subsubsection{{\tt fci\_ofind\_weight}}
974 \begin{verbatim}
975 subroutine fci_ofind_weight(iwalk,iocc)
976 implicit none
977 c
978 c find the lexical index of a path on the orbital graph
979 c
980 integer iwalk ! [output]
981 integer iocc(*) ! [input]
982 \end{verbatim}
983
984 \subsubsection{{\tt fci\_mfind\_occ}}
985 \begin{verbatim}
986 subroutine fci_mfind_occ(iwalk,iocc,ns)
987 c
988 c given the lexical index of a path on a primitive spin graph
989 c for ns electrons and multi=2sz+1, return the spin occupation
990 c
991 integer iwalk ! [input]
992 integer iocc(*) ! [output]
993 integer ns ! [input]
994 \end{verbatim}
995
996 \subsubsection{{\tt fci\_mfind\_weight}}
997
998 \begin{verbatim}
999 subroutine fci_mfind_weight(iwalk,iocc,ns)
1000 implicit none
1001 c
1002 c find the lexical index of a path on a primitive spin graph
1003 c for ns electrons and multi=2sz+1, given the spin occupation
1004 c
1005 integer iwalk ! [output]
1006 integer iocc(*) ! [input]
1007 integer ns ! [input]
1008 \end{verbatim}
1009
1010 \subsubsection{{\tt fci\_num\_dets}}
1011 \label{sec:fcinumdets}
1012 \begin{verbatim}
1013 integer function fci_num_dets(ns)
1014 c
1015 c return the number of determinants for ns open shell electrons
1016 c assuming that ns is a valid no. of open shell electrons for
1017 c the given FCI space and spin multiplicity
1018 c
1019 integer ns ! [input]
1020 \end{verbatim}
1021
1022 \subsubsection{{\tt fci\_num\_csf}}
1023 \begin{verbatim}
1024 integer function fci_num_dets(ns)
1025 c
1026 c return the number of configurations for ns open shell electrons
1027 c assuming that ns is a valid no. of open shell electrons for
1028 c the given FCI space and spin multiplicity
1029 c
1030 integer ns ! [input]
1031 \end{verbatim}
1032
1033 \subsubsection{{\tt fci\_num\_owalks}}
1034 \begin{verbatim}
1035 integer function fci_num_owalks()
1036 c
1037 c Returns the number of orbital occupation walks in the FCI
1038 c ignoring symmetry.
1039 c
1040 \end{verbatim}
1041
1042 \subsubsection{{\tt fci\_ndets}}
1043 \begin{verbatim}
1044 integer function fci_ndets()
1045 c
1046 c Returns the total number of determinants in the FCI
1047 c (with use of symmetry)
1048 c
1049 \end{verbatim}
1050
1051 \subsubsection{{\tt fci\_ncsf}}
1052 \begin{verbatim}
1053 integer function fci_ncsf()
1054 c
1055 c Returns the total number of spin-adapted configurations in the FCI
1056 c (with use of symmetry)
1057 c
1058 \end{verbatim}
1059
1060 \subsubsection{{\tt fci\_max\_num\_dets}}
1061 \begin{verbatim}
1062 integer function fci_max_num_dets()
1063 c
1064 c Returns the maximum number of determinants associated
1065 c with any orbital configuration in the full CI.
1066 c
1067 c [Note that occupations K that arise as a result of
1068 c .factorizations such as <I|Eij|J>=<I|Eia|K><K|Eaj|J>
1069 c .where a is a ficitious orbital, may have more open shells.
1070 c .However, these are only relevant in the internals of the
1071 c .coupling coefficient generation routines]
1072 \end{verbatim}
1073
1074 \subsubsection{{\tt fci\_owalk\_info}}
1075 \label{sec:fciowalkinfo}
1076 \begin{verbatim}
1077 subroutine fci_owalk_info(owalk, iocc, ns, ioff, numdet, sym)
1078 c
1079 c Given the index of an orbital walk return the occupation, the
1080 c offset in the CI determinant vector, the number of open shells,
1081 c the corresponding number of determinants, and the symmetry of
1082 c the occupation.
1083 c
1084 c The CI coefficients for this orbital occupation are addressed
1085 c as C(ioff+i) i=1,...,numdet.
1086 c
1087 c This routine bundles the function of several other routines
1088 c as a convenience.
1089 c
1090 integer owalk ! [input] Index of orbital occupation
1091 integer iocc(*) ! [output] The orbital occupation pattern
1092 integer ns ! [output] No. of open shells
1093 integer ioff ! [output] Offset into CI vector
1094 integer numdet ! [output] No. of determinants for this ns
1095 integer sym ! [output] Symmetry 0...7
1096 \end{verbatim}
1097
1098 \subsubsection{{\tt fci\_det\_to\_walk}}
1099 \begin{verbatim}
1100 subroutine fci_det_to_walk(idet, owalk, mwalk)
1101 c
1102 c Given the index of a determinant, idet, return the
1103 c corresponding lexical weights of orbital and primitive
1104 c spin functions. Without having an index vector the
1105 c length of the CI expansion the only way to do this
1106 c is with a binary search, so this operation costs
1107 c about log2(ndets).
1108 c
1109 integer idet ! [input] Index into determinant CI vector
1110 integer owalk ! [output] Corresponding orbital index
1111 integer mwalk ! [output] Corresponding primitive spin function index
1112 \end{verbatim}
1113
1114 \subsection{Transforming between CSF and determinats, and spin adaption}
1115
1116 \subsubsection{{\tt fci\_spin\_adapt}}
1117 \label{spinad1}
1118 \begin{verbatim}
1119 subroutine fci_spin_adapt(ns, direction, det, csf)
1120 c
1121 c Given a set of coefficients of either determinants or CSF
1122 c corresponding to a single orbital occupation with ns open shells,
1123 c then do the following
1124 c
1125 c if (direction == 1)
1126 c ... project from determinants to CSF with multiplicity multi (fci_setup)
1127 c ... if there is spin contamination norm will not be conserved
1128 c else if (direction == 2)
1129 c ... project from CSF with multiplicity multi to determinants
1130 c ... norm should be conserved
1131 c else
1132 c ... invalid value for direction
1133 c endif
1134 c
1135 integer ns ! [input] No. of open shells
1136 integer direction ! [input] 1=det to csf, 2=csf to det
1137 double precision det(*) ! [in/out] coefficients of determinants
1138 double precision csf(*) ! [in/out] coefficients of csf
1139 \end{verbatim}
1140
1141 The following related routine \verb+fci_spin_adapt_nvec()+ can
1142 transform multiple vectors (with the same number of open shells) at
1143 once, which is much more efficient.
1144
1145 \subsubsection{{\tt fci\_spin\_adapt\_nvec}}
1146 \begin{verbatim}
1147 subroutine fci_spin_adapt_nvec
1148 & (ns, direction, det, ldd, csf, ldc, nvec)
1149 c
1150 c Given NVEC sets of coefficients of either determinants or CSF
1151 c corresponding to a single orbital occupation with ns open shells,
1152 c then do the following
1153 c
1154 c if (direction == 1)
1155 c ... project from determinants to CSF with multiplicity multi (fci_init)
1156 c ... if there is spin contamination norm will not be conserved
1157 c else if (direction == 2)
1158 c ... project from CSF with multiplicity multi to determinants
1159 c ... norm should be conserved
1160 c else
1161 c ... invalid value for direction
1162 c endif
1163 c
1164 \end{verbatim}
1165
1166 \subsubsection{{\tt fci\_spin\_force}}
1167 \begin{verbatim}
1168 subroutine fci_spin_force(c)
1169 c
1170 c Force determinant CI vector to be spin adapted by projecting
1171 c to and from the CSF space. Also, renormalizes.
1172 c
1173 double precision c(ndets) ! [in/out] Determinant CI vector
1174 \end{verbatim}
1175
1176 \subsection{Coupling coefficients}
1177
1178 \subsubsection{{\tt fci\_couple1}}
1179
1180 \begin{verbatim}
1181 subroutine fci_couple1(vec, nvec, p, iocc, idim,
1182 & numq, qlist, epq)
1183 c
1184 c Compute <V|Epq|Iw> for given CI vectors V, fixed
1185 c orbital p, fixed orbital occupancy I (iocc), and all orbitals q
1186 c and primitive spin functions w.
1187 c
1188 c numq returns the number of orbitals q giving a nonzero interaction
1189 c
1190 c qlist(1...numq) contains the values of q
1191 c
1192 c epq(1...idim,1...nvec,1...numq) contains the coupling coeffcients
1193 c
1194 integer nvec ! [input] No. of vectors on the left hand side
1195 double precision vec(ndets,nvec) ! [input] The CI vectors
1196 integer p ! [input] Fixed label on Epq
1197 integer iocc(nactiv) ! [input] Orbital occupation of I
1198 integer idim ! [input] No. of spin functions for I
1199 integer numq ! [output] Returns the number of q
1200 integer qlist(*) ! [output] Returns the list of interacting q
1201 double precision epq(idim,nvec,*) ! [output] epq(w,i,q) = <Vi|Epq|Iw>
1202 \end{verbatim}
1203 % &
1204
1205 \subsubsection{{\tt fci\_couple2}}
1206 \begin{verbatim}
1207 subroutine fci_couple2(vec, nvec, p, r, iocc, idim,
1208 & numqs, qslist, epqrs)
1209 c
1210 c Compute <V|Epq,rs|Iw> for given CI vectors V, fixed orbitals
1211 c p and r, fixed orbital occupancy I (iocc), and all orbitals q and s,
1212 c and primitive spin functions w.
1213 c
1214 c The constraint (pq) >= (rs) is applied, so we loop over all q but
1215 c restrict the s loop. If couple2 is called with p>=r then all unique
1216 c coeffs are generated.
1217 c
1218 c numqs returns the number of orbitals q, s giving a nonzero interaction
1219 c
1220 c qslist(1, 1...numqs) contains the values of q
1221 c qslist(2, 1...numqs) contains the values of s
1222 c
1223 c epqrs(1...idim,1...nvec,1...numqs) contains the coupling coeffcients
1224 c
1225 integer nvec ! [input] No. of vectors on the left hand side
1226 double precision vec(ndets,nvec) ! [input] The CI vectors
1227 integer p, r ! [input] Fixed labels on Epq,rs
1228 integer iocc(nactiv) ! [input] Orbital occupation of I
1229 integer idim ! [input] No. of spin functions for I
1230 integer numqs ! [output] Returns the number of q, s
1231 integer qslist(2,*) ! [output] Returns the list of interacting q,s
1232 double precision epqrs(idim,nvec,*) ! [output] epq(w,i,q) = <Vi|Epqrs|Iw>
1233 \end{verbatim}
1234
1235 \subsubsection{{\tt fci\_couple3}}
1236 \begin{verbatim}
1237 subroutine fci_couple3(vec, nvec, p, q, r, t, iocc, idim,
1238 & numsu, sulist, epqrstu)
1239 c
1240 c Compute <V|Epq,rs,tu|Iw> for given CI vectors V, fixed orbitals
1241 c p,q,r,t and fixed orbital occupancy I (iocc), and all orbitals s,u
1242 c and primitive spin functions w.
1243 c
1244 c Constrain the loops over s and u so that (pq)>=(rs)>=(tu). If the
1245 c calling program externally constrains p>=r>=t (all q) then all
1246 c unique coupling coefficients will be generated.
1247 c
1248 c numsu returns the number of orbitals s,u giving a nonzero interaction
1249 c
1250 c sulist(1, 1...numsu) contains the values of s
1251 c sulist(2, 1...numsu) contains the values of u
1252 c
1253 c epqrstu(1...idim,1...nvec,1...numsu) contains the coupling coeffcients
1254 c
1255 integer nvec ! [input] No. of vectors on the left hand side
1256 double precision vec(ndets,nvec) ! [input] The CI vectors
1257 integer p, q, r, t ! [input] Fixed labels on Epq,rs,tu
1258 integer iocc(nactiv) ! [input] Orbital occupation of I
1259 integer idim ! [input] No. of spin functions for I
1260 integer numsu ! [output] Returns the number of s,u
1261 integer sulist(2,*) ! [output] Returns the list of interacting s,u
1262 double precision epqrstu(idim,nvec,*) ! [output] <Vi|Epqrstu|Iw>
1263 \end{verbatim}
1264
1265
1266 \subsection{Miscellaneous}
1267
1268 \subsubsection{{\tt fci\_onepdm}}
1269 \begin{verbatim}
1270 subroutine fci_onepdm(vec, nvec, onepdm)
1271 c
1272 c Compute the 1-particle density matrices
1273 c
1274 c onepdm(p,q,ivec) returns <V(ivec)|Epq|V(ivec)>
1275 c
1276 integer nvec ! [input] No. of vectors
1277 double precision vec(ndets, nvec) ! [input] The CI vectors
1278 double precision onepdm(nactiv,nactiv,nvec) ! [output] 1 PDMs
1279 \end{verbatim}
1280
1281 The program checks the 1-PDMs for symmetry and the correct trace and
1282 will abort if an error is detected.
1283
1284 The two-particle density matrix can also be generated with a small
1285 modification to this routine.
1286
1287 \subsubsection{{\tt fci\_hv}}
1288 \begin{verbatim}
1289 subroutine fci_hv(ecore, h, g, work, lenwrk, v, s)
1290 c
1291 c Compute the Hamiltonian matrix-vector product s = Hv
1292 c
1293 double precision ecore ! [input] Frozen-core+nuclear replusion energy
1294 double precision h(nacttr) ! [input] Effective 1-e integrals Core+T+V
1295 double precision g(nacttr,nacttr) ! [input] Two-electron integrals
1296 integer lenwrk ! [input] Size of workspace
1297 double precision work(lenwrk) ! [scratch] Workspace - the more the better
1298 double precision v(ndets) ! [input] CI vector
1299 double precision s(ndets) ! [output] s = H*v
1300 \end{verbatim}
1301
1302 The Davidson diagonalizer calls this routine so it should be reliable.
1303
1304 \subsubsection{{\tt fci\_hami}}
1305 \begin{verbatim}
1306 subroutine fci_hami(hamil, ecore, h, g, work, lenwork)
1307 c
1308 c Simple wrapper routine to build the full triangular Hamiltonian
1309 c in the determinant basis from the one- and two-electron integrals
1310 c
1311 double precision hamil(*) ! [output] Returns triangle of Hamiltonian
1312 double precision ecore ! [input] Frozen core + nuclear replulsion
1313 double precision h(nacttr) ! [input] Triangle of 1-e integrals
1314 double precision g(nacttr,nacttr) ! [input] 2-e integrals
1315 integer lenwork ! [input]
1316 double precision work(lenwork) ! [scratch]
1317 \end{verbatim}
1318
1319 \subsubsection{{\tt fci\_diags}}
1320 \begin{verbatim}
1321 subroutine fci_diags(hd,ecore,h,g,ionel,nonemx,kpt,mkpt)
1322 c
1323 c construct the diagonals of the hamiltonian
1324 c
1325 double precision hd(ndets) ! [output] The diagonals
1326 double precision ecore ! [input] Nuclear repulsion + frozen core
1327 double precision h(nacttr) ! [input] 1-e integrals
1328 double precision g(nacttr,nacttr) ! [input] 2-e integrals
1329 integer nonemx ! [input] dimension of ionel
1330 integer ionel(5,nonemx) ! [scratch] workspace for coupling coeff
1331 integer kpt(nonemx) ! [scratch] workspace
1332 integer mkpt(ndetmx+1) ! [scratch] workspace
1333 \end{verbatim}
1334 This is an internal interface to compute the diagonal elements on
1335 demand. It would be easy to provide an easy to use wrapper for this
1336 (see usage in \verb+fci_solve.F+) but since \verb+fci_solve+ (Section
1337 \ref{sec:fcisolve}) already writes the diagonals to disk there is
1338 not much point in using this routine elsewhere.
1339
1340 \subsubsection{{\tt fci\_prspnad}}
1341 \begin{verbatim}
1342 subroutine fci_prspnad(ns)
1343 integer ns ! [input]
1344 c
1345 c Print the spin-adaption coefficents for ns open shells
1346 c
1347 \end{verbatim}
1348
1349 \subsubsection{{\tt fci\_tprint}}
1350
1351 \begin{verbatim}
1352 subroutine fci_tprint()
1353 \end{verbatim}
1354
1355 This routine prints timing information to FORTRAN unit 6. If a
1356 routine is called more that $10^5$ times then to avoid too much system
1357 call overhead the timing is automatically disabled and the time
1358 reported as zero. The number of calls is still accumulated.
1359
1360 \subsubsection{{\tt fci\_err}}
1361 \begin{verbatim}
1362 subroutine fci_err(string, code)
1363 character*(*) string ! [input]
1364 integer code ! [input]
1365 \end{verbatim}
1366
1367 All errors in the full-CI code are reported through this routine.
1368 Put any additional error handling into this routine.
1369
1370 \begin{thebibliography}{99}
1371
1372 \addcontentsline{toc}{section}{References}
1373
1374 % \journal{label}{authors}{journal}{volume}{year}{page}
1375
1376 % \book{label}{authors}{title}{publisher}{year}
1377
1378 \book{pauncz}{R. Pauncz}{Spin functions: Construction and use}{Plenum,
1379 New York}{1979}
1380
1381 \book{paunczsym}{R. Pauncz}{The Symmetric Group in Quantum
1382 Chemistry}{CRC Press, Inc., Boca Raton, Florida, USA}{1995}
1383
1384 \journal{handyfci}{P. Saxe, D.J. Fox, H.F. Schaefer III and
1385 N.C. Handy}{J. Chem. Phys.}{74}{1982}{5584}
1386
1387 \journal{knowleseai}{P.J. Knowles and H-J. Werner}{Chem. Phys. Lett.}{145}{1988}{514}
1388
1389 \journal{duchug}{W. Duch}{Int. J. Quant. Chem.}{27}{1985}{59}
1390
1391 \journal{duchspinad}{W. Duch}{Int. J. Quant. Chem.}{30}{1986}{799}
1392
1393 \journal{duchcouple}{W. Duch}{Chem. Phys. Lett.}{124}{1986}{442}
1394
1395 \journal{duchfci}{W. Duch}{Intern. J. Quant. Chem}{S24}{1990}{683}
1396
1397 \journal{duchsga}{W. Duch and
1398 J. Karwowski}{Comp. Phys. Rep.}{2}{1985}{92}
1399
1400 \journal{paldusguga}{J. Paldus}{Phys. Rev. A}{14}{1976}{1620}
1401
1402 \journal{shavittguga}{I. Shavitt}{Int. J. Quant. Chem. Symp.}{11}{1977}{131}
1403
1404 \journal{shavittguga2}{I. Shavitt}{Int. J. Quant. Chem. Symp.}{12}{1978}{5}
1405
1406 \journal{saunders}{V.R. Saunders and J.H. van Lenthe}{Mol. Phys.}{48}{1983}{923}
1407
1408 \journal{zarrabian}{S. Zarrabian, C.R. Sarma and J. Paldus}{Chem. Phys. Lett.}{155}{1989}{183}
1409
1410 \journal{harrison}{R.J. Harrison and S. Zarrabian}{Chem. Phys. Lett.}{158}{1989}{393}
1411
1412 \book{kotani}{M. Kotani, A. Amemiya, E. Ishiguro and T. Kimura}{Tables
1413 of Molecular Integrals}{Maruzen, Co., Tokyo}{1955}
1414
1415 \end{thebibliography}
1416
1417 \end{document}
1418
1419