J.H. Langenberg

Theoretical Chemistry group

University of Utrecht 1989

revised version 1992


1 Description of CRESTR

1.1 Introduction

CRESTR is a support program for TURTLE, a program for Valence Bond calculations1. Its name is derived from CREate STRuctures. CRESTR's purpose is to define Valence Bond structures through spin projection of orbital configurations.
In this chapter, a brief description of CRESTR's possibilities is given, plus some technical details. Chapter 2 deals with input.

1.2 The aim of CRESTR

The task of CRESTR is to perform spin projections on chosen sets of configurations; the term configuration standing here for the distribution of electrons over space-orbitals. CRESTR defines symbolical Valence Bond structures. That is, numbers represent orbitals and the connection between these numbers and "real" orbitals is laid by the use of complementary programs.
CRESTR is able to construct both Rumer and branching diagram functions. For each configuration it generates all possible spin paths, but it the user is able to select if (s)he wants so. For the theory of the construction of spin eigenfunctions see for instance the author's report [1] or the paper by Raimondi et al. [2].
There are two ways in which configurations can be defined. The user can give them directly or (s)he can define a set of reference configurations and virtuals, with which CRESTR automatically generates new configurations by performing single and double excitations.
Finally, CRESTR contains a symmetry option. If the user adjusts irreps to orbitals, CRESTR removes all symmetry-forbidden configurations.

1.3 Some comments on the software

CRESTR is a FORTRAN program. It was written by Hans Langenberg, who had the aid of Joop van Lenthe and Koos Verbeek. The heart of the program consists of a spin projection procedure, based on leading terms [1,2], which generates Rumer functions. The construction of branching diagram functions is accomplished through Schmidt-orthogonalization of Rumer functions.
CRESTR is dynamically programmed. The request for core memory is settled in the main routine CRESTR by means of FORTRAN parameter NCORE. For most purposes 100000 words is sufficient. However, the required space rises rapidly if the maximum number of open shells per configuration exceeds 6. Other FORTRAN parameters like (M)MSOCC (20) can be raised without seriously effecting the amount of memory requested by the program.
CRESTR stores its results on an unformatted FORTRAN file. This file serves as an input source for TURTLE. The appendix describes the way this file should be read.

2 Input

2.1 General remarks

For all input-lines, the ATMOL input system is used, as described in the ATMOL-manual [3]. In lines defining configurations or determinants, orbitals are represented by integers. The value of integers representing orbitals should never exceed 253. A series of integers can always be given in a simplified form using the character string TO. Each row of integers may be closed with an optional END tag.

Example :

		1 2 4 5 6 7 8 10
can be replaced by
		1 2 4  TO  8 10  END
A row of orbitals may always be spread out over several lines. If the definition of a configuration or Slater-determinant includes tags or integers other than orbitals and is scattered among several lines, then the first field in each line must be an orbital. Furthermore, a new configuration or determinant should begin on a fresh line. Double occupied orbitals are defined by the twofold occurrence of an orbital.

2.2 Directives

All directives start with a keyword. The order in which the directives appear is immaterial, except that the first one must be the NELEC-directive and the last one the ENTER-directive.

2.2.1 The NELEC-directive (pre-directive)

This obligatory directive consists of the keyword NELEC, followed by the number of electrons.

Example :

		NELEC  3
The number of electrons equals 3.

Note that orbitals that remain frozen in a VBSCF calculation as specified in TURTLE input must be neglected in CRESTR input and thus do not add to the number of electrons above.

2.2.2 The PRINT-directive

This directive consists of the keyword PRINT, followed by a string representing the output-mode. If ALL is given, a large amount of output will be generated, considering all phases of program-execution. Amongst it is, for instance, the step by step formation of leading terms from configurations. LIMI or M show the defined structures and determinants. By default CRESTR gives sparse information.
The interpretation of the user-output CRESTR gives (if LIMI/M or ALL is requested) considering the definition of Valence Bond structures is explained in the following example:

	== list of configurations ==

	** configuration    1 **
		   1   1   2   2
		  structure   1  determinants   1
		    1 -1.00000

	** configuration    2 **
		   2   3   1   1
		  structure   1  determinants   2
		    1  0.70711  2 -0.70711
		  ******** determinants ********
		   1 : ba  2 : ab

	** configuration    3 **
		   1   2   3   4
		  structure   1  determinants   4
		    2  0.50000  3 -0.50000  4 -0.50000  5  0.50000
		  structure   2  determinants   4
		    1  0.50000  2 -0.50000  5 -0.50000  6  0.50000
		  ******** determinants ********
		   1 : bbaa  2 : baba  3 : baab  4 : abba  5 : abab
		   6 : aabb
The configurations are shown in ordered fashion: double occupied behind single occupied orbitals. Double occupieds are neglected in the spin-coupling procedure in CRESTR and are not shown in the Slater-determinants above. Consequently, for the first configuration in the example, which does not have any singly occupieds, no determinant is shown at all. The second configuration is projected into the following structure2 :

The third configuration is projected into two structures, which are interpreted as follows:

2.2.3 The MULT-directive

This directive consists of the keyword MULT, followed by the multiplicity. If omited, the multiplicity will equal 1 for even number of electrons and 2 for odd number of electrons.

Example :

		MULT  3
The wave function is threefold spin degenerate.

2.2.4 The SPIN-directive

This directive consists of the keyword SPIN, followed by a string representing the spin projection. If RUMER or LT is given, Rumer functions will be defined. Any of the strings BD, YK, or GEN, cause branching diagram functions to be defined. OFF defines (all possible) Slater-determinants as independent entities, that is, not gathered in structures. By default CRESTR defines Rumer functions. (See also the CONF-directive, 2.2.6.)

2.2.5 The SYM-directive

With this directive the irreducible representation of the wave function can be defined. It is used to exclude configurations of incorrect symmetry from the (symbolic) wave function. Note that the irreps of the orbitals must be determined by the user him- or herself, as this is not taken care of by TURTLE.
Input-lines :

The irreps of all present orbitals must be assigned. The pointgroups and corresponding irreps allowed for are the same as in ATMOL 4 DIRECT CI and can be found in the ATMOL-manual [4].

Example :

		D2H  AG
		AG  1  TO  4
		B1U  7 10
		B2U  6   9
		B3U  5   8

2.2.6 The CONF-directive

This directive is used to define one or more configurations.

Input-lines :

Each configuration must consist of NELEC orbitals.

example :

		1 1 2 2
		1 1 2 3
The first configuration consists of two closed shells, orbital 1 and 2, the second consists of one closed shell, orbital 1, and two open shells, orbital 2 and 3.
By default all structures corresponding to a configuration are formed by performance of the spin projection chosen with the SPIN-directive. However, the general approach will be overruled for a certain configuration if its definition is followed by a spin tag. For this tag, the same strings can be used as for the SPIN-directive (except OFF). If the tag is followed by integers, selected structures belonging to the particular configuration will be defined. In this case, the integers represent the selected spin paths. (By definition, the first spin path is the one that exhibits perfect pairing.) No more than 14 structures may be selected per configuration3.

Example :

		1 2 3 4
		1 2 3 5  RUMER
		1 2 4 5  BD  2
All (two) branching diagram functions are defined for the first configuration, and all Rumer functions for the second configuration. For the third configuration only the second branching diagram function is defined.
The user is protected against the multiple definition of one configuration. This protection will be overruled, for a particular configuration, if the user chooses to select structures as described above. The CONF-directive can not be combined with the MRSD-directive.

2.2.7 The STRUC-directive

This directive is used to define a structure manually. This structure may consist of any linear combination of Slater-determinants and need not necessarily be an eigenfunction of S2.

Input-lines :

Each determinant must consist of NELEC orbitals.

Example :

		1.0  1 2 3 4
		1.0  3 4 1 2
A (spin-unrestricted) Valence Bond structure is defined which, in case of singlet multiplicity, looks as follows:

The STRUC-directive may be applied only once and must not be used together with either the CONF- or the MRSD-directive.

2.2.8 The MRSD-directive

This directive is used to define a set of reference configurations and a group of virtual orbitals, with which single and double excitations will be performed. The excitations can be defined in two, distinct ways. In the first one (CONF), configurations serve as the reference space. After all single and double excitations to a certain virtual space have been carried out, spin projection is performed to all acquired configurations. In the second one (STRUC), the subject of the excitations is formed by Valence Bond structures, obtained by spin projection of reference configurations. The singles and doubles are generated by one- and twofold appliance of an excitation operator, which, in second quantization language, is defined as v a + o(-,v) o(-,a), where v represents a virtual orbital and a an active. Applied to a spin eigenfunction, this operator generates spin eigenfunctions, and no spin projection needs to be carried out afterwards.

Input-lines :

Example :

		1 1 2 2 3 3 4 4 6
		1 1 2 2 3 3 5 5 7
		8 9 10

Correlating configurations are generated by single and double excitations of the two reference configurations to the virtual orbitals 8, 9, and 10. Spin projection is performed after generation of the configurations.

2.2.8 The ENTER-directive

This obligatory directive consists of the single keyword ENTER and is used to close an input-session.

2.3 Example

		MULT  1
		1 1 2 2
		1 1 2 3
		1 1 2 4
		1 2 2 3
		1 2 2 4


[1] J.H. Langenberg, De definitie van Valence Bond-structures. Doctoraalverslag van Hans Langenberg, Utrecht, 1988
[2] M.Raimondi, M. Simonetta and G.F. Tantardini, Ab initio Valence Bond Theory, Computer Physics Reports, Vol 2, 1985, p 171
[3] V.R. Saunders, ATMOL 3 Part 2 Card Input Conventions, 1976
[4] J.H. van Lenthe, ATMOL 4 DIRECT CI Users Guide, Utrecht, 1984

Appendix: The use of CRESTR-output

1 Introduction

The communication of CRESTR with TURTLE is arranged via FORTRAN file TAPE15.DATA. As a debugging tool an independent program exists, READ15, which can read this file and print its information. The reading-part of this program including the meaning of the gathered variables and arrays is demonstrated in paragraph 2. The logical structure of the data is treated in paragraph 3.

2 The main elements of READ15

Data are read from TAPE15 by the use of unformatted READ-statements. In the following, the reading of TAPE15 is treated in chronological order. FORTRAN-statements are shown in bold type. Array- or variable-names beginning with I to N refer to integers, all others refer to reals (except for the variable MANUAL, which is type logical). REWIND (15) READ (15) NELEC, NALPHA, NCONF, NTDET, NTSTRU, MAXDET, & MAXSTR, NWPAC, NCFFF, IMAX, MANUAL NELEC : number of electrons
NALPHA : number of alpha-electrons
NCONF : number of configurations
NTDET : number of determinants
NTSTRU : number of structures
MAXDET : maximum number of determinants per configuration
MAXSTR : maximum number of structures per configuration
NWPAC : number of words in which all packed determinants are stored
NCFFF : total number of references to determinants
IMAX : highest orbital number
MANUAL : logical; if its value equals .true., the STRUC-directive has been used

KDETPS(I) : number of determinants that define structure I
IDETPS(1) to IDETPS(KDETPS(1)) : determinants that define structure 1
IDETPS(KDETPS(1)+1) to IDETPS(KDETPS(2)) : determinants that define structure 2

COEFFF(I) : the coefficient that belongs to the determinant refered to by IDETPS(I)
KNTDET(I) : number of determinants that belong to configuration I
KNSTRU(I) : number of structures that belong to configuration I
PACDET : determinants in packed form
READ (15) ((KCONF(I,J), I=1,NELEC+1), J=NCONF) KCONF(1,J) to KCONF(NELEC,J) : orbitals that belong to configuration J
KCONF(NELEC+1,J) : number of closed shells that belong to configuration J
(KCONF is not read if manual equals .true.)

Unpacking the determinants is accomplished in the following statements. (The UNPACK-routine is found at the ATMOL library libatm.a.)

	II = 1
	IDET = 1
	DO 10 I=1,NCONF
    &                                NELEC*KNTDET(I))
		II = II + ((KNTDET(I)*NELEC-1)/8) + 1
KDETER(1,J) to KDETER(NELEC,J) : orbitals that define determinant J

3 The CRESTR-definition of structures

Each series of NELEC integers on KDETER corresponds to one Slater-determinant (not written in anti-symmetrised form). The first NALPHA orbitals of one determinant have alpha-spin, the remaining beta-spin. The determinants are grouped in configurations. The first KNTDET(1) determinants belong to configuration 1, the subsequent KNTDET(2) determinants belong to configuration 2, etc.

Each structure is defined by references to determinants (on IDETPS), provided with coefficients. The first KDETPS(1) references on IDETPS define structure 1, the next KDETPS(2) references define structure 2, etc. The coefficient that belongs to the determinant refered to by IDETPS(I) is COEFFF(I).

The structures are grouped in configurations in the same way as the determinants are. The first KNSTRU(1) structures belong to configuration 1, the next KNSTRU(2) structures belong to configuration 2, etc. IDETPS(I) gives the position of a determinant on KDETER within the configuration to which it belongs.


1. In future versions of TURTLE, CRESTR will be an integrated part of the program.
2. Note that internally, Slater-determinants are stored a/b blocked, and outputting them as above may be accompanied by a change of sign in some coefficients.
3. This number can be raised easily by altering the statement DATA MAXSP/14/... in the main routine CRESTR.