Table of Contents

Variables

Data may be stored in variables. A variable can be of type string, real or logical, depending on the type of the expression in its definition. Any sequence of characters which is not recognized as expression or variable is treated as string. In this section, we will discuss only real and logical variables. String variables will be discussed in more detail in section string variables. Variables can be used anywhere in the input, but they can be set only outside the input blocks for specific programs. For example, if a variable is used within the input block for HF, it must have been set before the HF{...} input block.

Molpro automatically stores various results and data in system variables (see section variables set by the program), which can be used for further processing. A new feature of Molpro2002 is that most system variables are write protected and cannot be overwritten by the user. The input is automatically checked before the job starts, and should a system variable be set in the input the job will stop immediately with an error message. Only in some exceptions (see section system variables), system variables can be modified using the SET command (but not with the simple NAME=value syntax). Note that due to the changed usage and syntax of the SET command, compatibility with Molpro92 input syntax is no longer maintained.

Setting variables

A variable can be defined using

variable1=value1, variable2=value2, …

A variable definition is recognized by the equals sign in the first field of the input card. For example,

THRESH,ENERGY=1.d-8,GRADIENT=1.d-5

does not define variables; here ENERGY and GRADIENT are options for the THRESH directive.

Variables can have different types:

expression [,] [unit]
unit is an optional string which can be used to associate a unit to the value. ANG[STROM], DEGREE, HARTREE are examples. Undefined variables in expressions are assumed to be zero (and defined to be zero at the same time).

Indexed variables

Variables can be indexed, but only one-dimensional indexing is available. Indexed variables can be defined either individually, e.g. 

R(1)=1.0 ANG
R(2)=1.2 ANG
R(3)=1.3 ANG

or as a vector of values enclosed by square brackets:

R=[1.0,1.1,1.2] ANG

Subranges can also be defined, e.g. 

R(1)=1.0 ANG
R(2:3)=[1.1,1.2] ANG

leads to the same result as the above two forms.

The type of each element depends on the type of the assigned value, and it is possible to mix types in one variable. Example: 

geometry={he}
hf
result=[program,energy,status.gt.0]

yields: 

RESULT(1)      =    HF-SCF
RESULT(2)      =        -2.85516048  AU
RESULT(3)      =    TRUE

In this example the variables PROGRAM, ENERGY, and STATUS are system variables, which are set by the program (see section system variables).

String variables

As explained already in section setting variables, string variables can be set as other variables in the form

variable = ’string’
variable = string_variable

Strings must be enclosed by quotes. Otherwise the string is assumed to be a variable, and if this is undefined it is assumed to be zero.

Alternatively, if the name of the variable is preceded by a dollar ($), all values are assumed to be a string. This can be a string variable, a quoted string, or an unquoted string. Note that unquoted strings are converted to upper case. Also note that quotes are compulsory if the string contains blanks.

Example:

$str=[a,b+4,’This is an example for strings’]

yields 

STR(1)         =    A
STR(2)         =    B+4
STR(3)         =    This is an example for strings

As a general rule, string variables are replaced by their value only if they are preceded by a dollar ($) (exceptions: in variable definitions, on ''SHOW'' cards, and in logical expressions on ''IF'' cards, the dollar is optional). This is a precaution to avoid commands which have the same name as a variable being interpreted as variables. Variables may also appear on ''TEXT'' or ''TITLE'' cards or in strings, but must be preceded by $ in these cases. Example: 

$METHOD=MCSCF
R=1.5
TEXT,$method results for R=$R Bohr

prints

MCSCF results for R=1.5 Bohr

String variables can be concatenated with strings or other string variables in the following way. Assume that variable PROGRAM has the value MRCI. Setting

METHOD=’$PROGRAM+Q’

sets METHOD to MRCI+Q. Alternatively, if we would also have a variable VERSION with value Q, we could write

METHOD=’$PROGRAM+$VERSION’

Again, the value of METHOD would be MRCI+Q. Note that the quotes are necessary in these cases.

Substring operations are not implemented.

System variables

As mentioned above, most system variables cannot be written by the user. In some exceptions, it is possible to redefine them using the SET command:

SET,variable = expression [,] [unit]

This holds for the following variables:

Macro definitions using string variables

String variables for which the stored string has the form of an algebraic expression are evaluated to a number if they are preceded by two dollars ($$). Example: 

string='a+b'
a=3
b=4
text,This is string $string which evaluates to $$string

prints

* This is string a+b which evaluates to 7

This can be used to define simple macros, which can be used at various places in the subsequent input. For instance, 

ECORR='ENERGY-ESCF' !define a macro
HF                  !do SCF calculation
ESCF=ENERGY         !store SCF energy in variable ESCF
MULTI               !do CASSCF
DEMC=$$ECORR        !store CASSCF correlation energy in variable DEMC
MRCI                !do MRCI
DECI=$$ECORR        !store MRCI correlation energy in variable DECI

Here is an example of advanced use of macros and string variables:

examples/oh_macros.inp
***,test for parser
text,This fancy input demonstrates how string variables and macros can be used
text
basis=vdz               !define basis set
geometry={O;H,O,r}      !define geometry (z-matrix)

text,methods
$method=[rhf,2[casscf,2[mrci]]]
text,active spaces
$spaces=['[3,1,1]',3['[4,2,2]'],3['[5,2,2]']]
text,symmetries
$symset=['1',2['[1,2,3]','1','2']]
text,weight factors for state averaged casscf
$weights=['1','[1,1,1]',2[' '],'[1,0.5,0.5]',2[' ']]
text,scf occupation
set,scfocc=[3,2[1]]
text,bond distance
r=1.85

hf
do i=1,#method         !loop over methods
mcocc=$$spaces(i)      !set active space for this run
set,symmetry=$$symset(i)   !set symmetries for this run
set,weight=$$weights(i)    !set weights for this run
$method(i)             !now run method
e(i)='$energy'         !save energies in strings
dipol(i)='$dmz'        !save dipole moments in strings
enddo
table,method,spaces,symset,weights,e,dipol
title,Results for OH, r=$r, basis=$basis
head,method,spaces,symmetries,weights,energies,'dipole moments'
exit

Indexed Variables (Vectors)

Variables may be indexed, but only one-dimensional arrays (vectors) are supported. The index may itself be a variable. For instance

METHOD(I)=PROGRAM
E(I)=ENERGY

are valid variable definitions, provided I, PROGRAM, and ENERGY are also defined variables. Indices may be nested to any depth.

Different elements of an array can be of different type (either real or logical). However, only one unit can be assigned to an array. String variables have no associated value and cannot be mixed with the other variable types. Therefore, a given variable name can only be used either for a string variable or a real (logical) variable.

Vectors (arrays) can be conveniently defined using square brackets:

R=[1.0,1.2,1.3] ANG

This defines an array with three elements, which can be accessed using indices; for instance, R(2) has the value 1.2 ANG. A repeat specifier can be given in front of the left bracket: 5[0] is equivalent to [0,0,0,0,0]. Brackets can even be nested: for instance, 2[1,2,2[2.1,3.1]] is equivalent to [1,2,2.1,3.1,2.1,3.1,1,2,2.1,3.1,2.1,3.1].

Arrays can be appended from a given position just by entering additional elements; for instance,

R(4)=[1.4,1.5] ANG

or

R(4:)=[1.4,1.5] ANG

extends the above array to length 5. Previously defined values can be overwritten. For instance

R(2)=[1.25,1.35,1.45]

modifies the above vector to (1.0, 1.25, 1.35, 1.45, 1.5).

If no index is given on the left hand side of the equal sign, an existing variable of the same name is replaced by the new values, and all old values are lost. For instance

Square brackets can also be used to define an array of strings, e.g.,

METHOD=[INT,HF,CASSCF,MRCI]

These could be used as follows: 

DO I=1,4
$METHOD(I)
ENDDO

The above input would be equivalent to 

INT
HF
CASSCF
MRCI

The current length of an array can be accessed by preceding # to the variable name. For instance, in the above examples #R and #METHOD have the values 5 and 4, respectively. If a variable is not defined, zero is returned but no error occurs. This can be used to test for the existence of a variable, for example:

IF(#SPIN.EQ.0.AND.#NELEC.EQ.1) SET,SPIN=MOD(NELEC,2)

This defines variable SPIN if it is unknown and if NELEC is a scalar (one dimensional) variable.

Vector operations

The following simple vector operations are possible:

At present, vector operations are not supported with string variables.

Special variables

Variables set by the program

A number of variables are predefined by the program. The following variables can be used to convert between atomic units and other units: 

EV=1.d0/27.2113839d0 HARTREE
KELVIN=1.d0/3.157747d5 HARTREE
KJOULE=1.d0/2625.500d0 HARTREE
KCAL=1.d0/627.5096d0 HARTREE
CM=1.d0/219474.63067d0 HARTREE
CM-1=1.d0/219474.63067d0 HARTREE
HZ=1.d0/6.5796839207d15 HARTREE
HERTZ=1.d0/6.5796839207d15 HARTREE
ANG=1.d0/0.529177209d0 BOHR
ANGSTROM=1.d0/0.529177209d0 BOHR

TOEV=27.2113839d0 EV
TOK=3.157747d5 K
TOKELVIN=3.157747d5 K
TOCM=219474.63067d0 CM-1
TOHERTZ=6.5796839207d15 HZ
TOHZ=6.5796839207d15 HZ
TOKJ=2625.500d0 KJ/MOL
TOKJOULE=2625.500d0 KJ/MOL
TOKCAL=627.5096d0 KCAL/MOL
TOA=0.529177209d0 ANGSTROM
TOANG=0.529177209d0 ANGSTROM
TODEBYE=2.54158d0 DEBYE

Further variables which are set during execution of the program:

The variable names for properties are the same as used on the EXPEC input cards.

By default, only the dipole moments are computed and defined. The values of other properties are only stored in variables if they are requested by EXPEC cards. If more than one state is computed (e.g., in state-averaged MCSCF, corresponding arrays PROP(istate) are returned. If properties are computed for more than one center, the center number is appended to the name, e.g. EFX1, EFX2 etc.

If transition properties are computed, their values are stored in corresponding variables with prefix TR, e.g., TRDMX, TRDMY, TRDMZ for transition dipole moments. If more than two states are computed, the index is $(i-1)*(i-2)/2+j$, where $i \gt j \ge 1$ are state numbers. In a state-averaged calculation, states are counted sequentially for all state symmetries.

For instance, in the following state-averaged MCSCF

MULTI;WF,14,1,0;STATE,3;WF,14,2,0;STATE,2;WF,14,3,0

the states are counted as

$i$ 1 2 3 4 5 6
Symmetry 1 1 1 2 2 3
Root in Sym. 1 2 3 1 2 1

Variables recognized by the program

All variables described below are checked by the program, but not set (except NELEC and SPIN). If these are not defined by the user, the program uses its internal defaults. The variables are only recognized and used if defined using the SET command, e.g.

SET,MCOCC=[6,3,2]
SET,STATE=2

etc.

Variables recognized by the SCF program:

Variables recognized by the MCSCF program:

Variables recognized by the CI/CCSD program:

Variables recognized by the DFT/KS program:

Example for the use of these variables for a state-averaged MCSCF (note that system variables can only be modified using the SET command, see section system variables):

Note: Setting the variables NELEC, SPIN, or SYMMETRY, has the same effect giving these on a gobal WF directive. If the global WF directive is given after the variable definition, the values of the variables are replaced by the values given on the WF directive. Vice versa, if a variable definition follows a gobal WF directive, the new value of the variable is used in the following. Note that WF input cards in command blocks have preference over global WF directives or input variables.

Displaying variables

Variables or the results of expressions can be displayed in the output using SHOW and TABLE.

The SHOW command

The general form of the SHOW command is as follows:

SHOW[ncol,format],expression

where expression can be an expression or variable, ncol is the number of values printed per line (default 6), and format is a format (default 6F15.8). This can be used to print vectors in matrix form. The specification of ncol and format is optional. Assume that E is a vector:

Note that the total length of the format should not exceed 100 characters (a left margin of 30 characters is always needed).

A wild card format can be used to show several variables more easily:

SHOW,qm*,dm*

shows all variables whose names begin with QM and DM. Note that no letters must appear after the , i.e., the wild card format is less general than in UNIX commands.

See the TABLE command for another possibility to tabulate results.

Clearing variables

Variables can be deleted using

CLEAR,name1, name2, …

Wild cards can be used as in SHOW, e.g.,

CLEAR,ENERG*

clears all variables whose names begin with ENERG. All variables can be cleared using

CLEARALL

The length of vectors can be truncated simply by redefining the length specifier: #R=2 truncates the array R to length 2. Higher elements are no longer available (but could be redefined). Setting #R=0 is equivalent to the command CLEAR,R.

Reading variables from an external file

Variables can be read from an external file using

READVAR, filename, [option]

Such files can be saved, for instance by the geometry optimization program, and reused later to recover a certain optimized geometry. The format of the input in filename is the same as for ordinary input.

If option=NOINDEX|IGNOREINDEX is given then variable indices are ignored and only the last value saved is read (without index). This can be useful if for example a file saved with SAVEACT in a geometry optimization is read, and it is intended to continue with the variables that were saved last.