Z-Matrix Manipulation

Introduction

The z-matrix, or internal co-ordinate, definition of a molecular structure is probably the most important way of inputting and manipulating chemical structures, particularly for small-molecule work. A number of utility routines are described.

NB The routines in this chapter describe a z-matrix definition that allows the inclusion of atoms defined by their cartesian co-ordinates, along with internal co-ordinate atoms. This is designed to be useful when an internal co-ordinate definition of an active site is to be added to a macromolecular system which is defined in cartesian co-ordinates. At the moment, the only optimisation code within ChemShell that supports geometry optimisation in mixed internal/cartesian co-ordinates is the zopt function implemented in the newopt package.

Z-matrix Manipulation Functions

The following commands set up and manipulate the z-matrix structure.

List of Functions in this section:

z_create

Command Line Arguments

Argument	Argument type	Mandatory	Default	To specify
zmatrix	Zmatrix tag	yes	-	Identifier for the resulting z-matrix object
var_list	Tcl variable name	no	-	Variable to hold hessian information
last argument	Tcl list	yes	-	Z-matrix contents

Description:

z_create zmatrix=z {
zmatrix angstrom
o
h 1 oh1
h 1 oh2 2 110.0
variables
oh1 1.0
constants
oh2 1.1
end
}

The zmatrix line may be optionally followed by a unit specification (e.g. angstrom above) to indicate the unit of length used. The default is au, with angles specified in degrees. The unit specification may also be given on the variables and constants records, enabling different length units to be mixed in the same input stream. If unit specification is not given on these records, they inherit the specification from the last record it was specified on.

It is also possible to define a z-matrix without explicit use of the atom index numbers. Atom symbols may be used instead, provided that the symbols are unique. This practice allows atoms to be inserted (or deleted) without relabelling the z-matrix.

If you want to use symbolic atom indices i.e. label an atom with a symbol and number that can be referred to from else where in the z-matrix, you can do so with the form <symbol>%<index>, e.g. h%1. Using this method, you can remove atoms from the z-matrix, without interfering with the z-matrix's internal labelling system (as long as you did not remove an atom that is itself referred to by another atom). When the z-matrix is passed on to other codes form the TCL, the symbolic atom indices are replaced with conventional indices so that multiple instances of the same type of atom are not treated as different atoms. When passed from TCL, <symbol> will be retained, while <index> will only be used internally by TCL for the cross-indexing of atom records. This is most easily illustrated by the following example.

z_create zmatrix=z {
zmatrix angstrom
o
h%1 1 oh1
h%2 1 oh2 h%1 110.0
variables
oh1 1.0
constants
oh2 1.1
end
}

The labels h%1 and h%2 allow the final atom (h%2) to be defined unambiguously by an angle from h%1. However, the two atoms will both have symbol h in subsequent calculations.

Atoms defined in cartesian co-ordinates may be added using the coordinates keyword, as shown below (in a rather unlikely example).

z_create zmatrix=z {
coordinates angstrom
mg1  0.   0.   0.
mg2  0.   0.   mg2z
mg3  1.   0.   1.
mg4  1.   0.   0.
zmatrix
o   mg1   mgo   mg2  90.0   mg3  -90.0
h1  o     oh1   mg1  mgoh   mg2    0.0
h2  o     oh2   h1   hoh    mg2  180.0
variables au
mg2z  1.0
variables angstrom
oh1 1.0
variables au
oh2 1.1
hoh 120.
mgo 2.0
mgoh 120.0
end
}

The following points should be noted for mixed cartesian/internal definitions.

• The two types of records may appear in any order, and the coordinates and zmatrix keywords may be used multiple times.
• If any of the first three atoms is cartesian, the position and orientation conventions of the z-matrix should be followed - i.e.:
  • Atom 1 at the origin
  • Atom 2 on the +z axis
  • Atom 3 in the xz plane.
• Internal co-ordinate definitions may be may be given in terms of cartesian atoms.
• All cartesian co-ordinates are treated as fixed unless specified as variables, in the same manner as internal co-ordinates.
• The units used for cartesian co-ordinates may be either Å (angstrom) or Bohr (au). The default is Bohr. The unit may be changed on any coordinates, zmatrix, constants, and variables directive. Note that in this way, variables and constants defined in a block with angstrom length-unit may be input in au length-unit (as is done for the variables mg2z, oh2, and mgo in the above example. If the unit is not specified it is inherited from the previous definition.
• See note at the beginning of this chapter regarding geometry optimisation.

Control information for the computation of the hessian may be incorporated in the z-matrix definition, just as in GAMESS-UK, by tagging it on to the variables input lines. There are currently three valid options: a number and the keywords fd and fd2. This information will get passed into the var_list string for subsequent use.

The atomic charge associated with a centre may be provided by appending the "charge" keyword and the charge value to the Z-matrix line. In the absence of this keyword the atomic charge is undefined.

The optional var_list argument specifies the name of a Tcl variable which will hold the results of processing any such keywords, formatted as a Tcl list. The hessian is only affected if this string is subsequently used in the hessian command.

Tagging on a number will then cause the diagonal element of the hessian for the variable to take on the specified value; the keywords fd and fd2 will cause finite-differencing of the gradients by the one-, respectively two-point formula to generate a row and a column of the hessian for the variable.

z_create zmatrix=z var_list=varlist {
zmatrix angstrom
o
h 1 oh1
h 1 oh2 2 hoh
variables
oh1 1.0     0.3
hoh 110.    fd2
constants
oh2 1.1
end
}

In this example, the Tcl variable varlist contains the string {1 0.3} {2 fd2}, which, passed on to the hessian command, causes the hessian element for the O-H stretch to be 0.3, and the hessian elements associated with the H-O-H bend to be determined by the two-point finite-difference formula.

z_create is not the only module that requires z-matrix input. Others, such as hybrid_setup take the z-matrix data, along with other information, and create z-matrix objects as a result.

z_substitute

Command Line Arguments

Argument	Argument type	Mandatory	Default	To specify
zmatrix	Zmatrix tag	yes	-	Identifier for the resulting z-matrix object
values	Tcl list	yes	-	Variable to hold hessian information

Description:

z_create zmatrix=z {
o1
o2   1   r21
h1   1   r31   2   a312
h2   2   r42   1   a421   3   t4213
variables
r21     2.45700
r31     2.07859
r42     2.07835
a312    100.001
a421    100.003
t4213   29.0
end
}

z_substitute zmatrix=z values= {r21=3.0 r31=2.0}
z_list zmatrix=z

z_prepare_input

Command Line Arguments

Argument	Argument type	Mandatory	Default	To specify
zmatrix	Zmatrix tag	yes	-	Identifier for the z-matrix object

Description:

z_recalc

Command Line Arguments

Argument	Argument type	Mandatory	Default	To specify
zmatrix	Zmatrix tag	yes	-	Identifier for the z-matrix object
coords	Fragment tag	yes	-	Fragment object containing reference coordinates
change_constants	yes/no	no	-	Whether to modify constant values

Description:

Often, if a z-matrix has been derived for one structure or conformation of a system, it is convenient to use it as a template to generate a z-matrix for another conformation, for which only the co-ordinates are known. This can be performed by the z_recalc command. The format is

z_recalc zmatrix=z coords=c

z is the z-matrix, which will be replaced by the new one, and c the molecular fragment definition for which the z-matrix is required. The z_recalc procedure will not modify parameters in the input z-matrix that are not specified as variables. Where the same variable is used for more than one geometrical parameter within the molecule, the final value of the variable will be taken as the mean of the corresponding geometrical parameters of the molecule.

z_set_atom_charge

Command Line Arguments

Argument	Argument type	Mandatory	Default	To specify
zmatrix	Zmatrix tag	yes	-	Identifier for the z-matrix object
atom_number	integer	yes	-	Which atom to edit
charge	double	yes	-	Required Charge

Description:

z_var

Command Line Arguments

Argument	Argument type	Mandatory	Default	To specify
zmatrix	Zmatrix tag	yes	-	Identifier for the z-matrix object
result	Zmatrix tag	yes	-	Output zmatrix
previous_hessian	Matrix tag	no	-	Last hessian of the new size
original_hessian	Matrix tag	no	-	Hessian corresponding to the old variable specification
new_hessian	Matrix tag	no	-	Result hessian
var_list	Tcl variable name	no	-	Variable in calling routine to hold the control data for hessian evaluation

Description:

The simplest invocation of z_var is as follows:

z_var zmatrix=z result=z2 control= {release all}

The control string specifies the required change to the z-matrix. ``release all'' will make independent variables from all degrees of freedom. The control string may consist of a number of components, separated by commas. Each component may consist of a keyword (as specified in the table), followed by a specification of the list of variables or degrees of freedom to be modified.

keyword	type	Effect
release	name or number	release specified degrees of freedom
release_atom	number	release all degrees of freedom of this atom
freeze	name or number	freeze specified degrees of freedom
freeze_atom	number	freeze all degrees of freedom of this atom
unshare	name or number	make specified degrees of freedom defined by the same variable independent

The variable specification following the keyword may take a number of forms.

1.

The keyword all, to specify all appropriate degrees of freedom.

2.

A variable or constant name (as specified in the z-matrix input).

3.

A symbolic reference to the degree of freedom. This is composed of one of the following letters to signify the position in the zmatrix of the relevant degree of freedom, followed by the index of the atom concerned.

r

a bond length

a

a bond angle

t

a torsion angle

x

an x-co-ordinate

y

a y-co-ordinate

z

a z-co-ordinate

4.

An integer, indicating the index into a list of the 3N-6 degrees of freedom (bonds or z-co-ordinates, followed by angles or x-co-ordinates, followed by torsions and y-co-ordinates).

To modify an existing hessian matrix in a corresponding manner, it is necessary to pass either two or three extra arguments to z_var.

If the number of variables is being reduced, the effect on the hessian is simply to delete the corresponding rows and columns. The original_hessian and new_hessian arguments are used pass the names of the corresponding hessian matrices. (See Sections on modules opt and newopt for information on on the generation and use of internal coordinate hessian matrices). A simple example of the reduction of the hessian is given below:

z_create  zmatrix=z1 {
zmatrix
o
h%1   o   oh1
h%2   o   oh2  h%1   hoh
variables angstrom
oh1  1.0
oh2  1.0
hoh  100.0
end
}
#
# partially optimise the full zmatrix
#
newopt function=zopt: {zmatrix=z1 \
theory=gamess : { basis=dzp listing=gamess.out } }\
maxstep=2 \
final_hessian=h1

After this partial optimisation, the angle variable is frozen and the remaining variables are optimised.

#  continue from previous example - remove angle from variable list
#
z_var zmatrix=z1 result=z2 \
control= {freeze hoh} \
original_hessian=h1 new_hessian=h2

#
# converge the remaining variables
#
newopt function=zopt: {zmatrix=z2 \
theory=gamess : { basis=dzp listing=gamess.out } }\
input_hessian=h2 \
final_hessian=h2

In cases where the number of variables is being increased, extra rows and columns are added to the hessian. By default these are taken from a unit matrix. However, in many cases, the new (larger) z-matrix may have been used in a previous optimisation, before the constraints were applied. If this is so, the previous version of the large hessian may provide a better estimate for the new rows and columns. This behaviour may be requested by specifying the older matrix with the previous_hessian argument. Consider reversing the transformation given above, recovering the hessian information from matrices h1 and h2.

#  continue from previous example - restore angle to variable list
#
z_var zmatrix=z2 result=z3 \
control= {release hoh} \
original_hessian=h2 new_hessian=h3 previous_hessian=h1

newopt function=zopt: {zmatrix=z3 \
theory=gamess : { basis=dzp listing=gamess.out } }\
input_hessian=h3

z_gen

Command Line Arguments

Argument	Argument type	Mandatory	Default	To specify
zmatrix	Zmatrix tag	yes	-	Identifier for the resulting z-matrix object
last argument	Tcl list	yes	-	Cartesian coordinates and atom indices

Description:

The z_gen command allows a z-matrix to be constructed given cartesian co-ordinates and a specification of the atom indices from which the bond length, angle, and torsion definitions are derived.

The input is presented as the last argument to the z_gen command and includes, for each atom, a record consisting of the symbol, the co-ordinates, and the atom indices from which you wish to define the internal co-ordinates. No variable or constant definitions are generated. The input data should be presented in a.u.

The following example will construct a z-matrix for hydrogen peroxide from cartesian co-ordinates.

z_gen zmatrix=z {
o  0.0    0.0     0.0
o  0.0    0.0     2.457  1
h  2.047  0.0     -.361  1 2
h -.18    2.0390  2.818  2 1 3
}

will generate the zmatrix

o
o       1    2.45700
h       1    2.07859    2  100.00159
h       2    2.07852    1  100.00193    3   95.04491

To generate a z-matrix in which all parameters are variable, the command z_var may be used on the resulting z-matrix.

Z-matrix Inquiry Functions

The following commands are used for querying defined z-matrices

List of Functions in this section:

z_list

Command Line Arguments

Argument	Argument type	Mandatory	Default	To specify
zmatrix	Zmatrix tag	yes	-	Identifier for the z-matrix object

Description:

z_to_c

Command Line Arguments

Argument	Argument type	Mandatory	Default	To specify
zmatrix	Zmatrix tag	yes	-	Input zmatrix
coords	Fragment tag	yes	-	Identified for output fragment object (will be created)
delete_dummies	text	no	-	Whether to delete dummy atoms, (default is yes)

Description:

c_to_z

Command Line Arguments

Argument	Argument type	Mandatory	Default	To specify
zmatrix	Zmatrix tag	yes	-	Output zmatrix (will be created)
coords	Fragment tag	yes	-	Input fragment object
rotate	boolean	no	-	Whether to rotate or add dummies

Description:

The requirement that the first zmatrix atom should be at the origin is (by default) satisfied by adding 3 dummy atoms (symbol x) to the start of the zmatrix. If the argument rotate=yes is provided, these dummies are not added, and a translation/reorientation of the molecule to place atom 1 at origin, atom 2 at +z etc is performed.

z_get_variable_value

Command Line Arguments

Argument	Argument type	Mandatory	Default	To specify
zmatrix	Zmatrix tag	yes	-	Identifier for the resulting z-matrix object
index	integer index	yes	-	Which variable to interrogate

Description:

z_set_variable_value

Command Line Arguments

Argument	Argument type	Mandatory	Default	To specify
zmatrix	Zmatrix tag	yes	-	Identifier for the z-matrix object
index	integer index	yes	-	Which variable to set

Description:

z_number_of_variables

Command Line Arguments

Argument	Argument type	Mandatory	Default	To specify
zmatrix	Zmatrix tag	yes	-	Identifier for the z-matrix object

Description:

z_freeze_variable

Command Line Arguments

Argument	Argument type	Mandatory	Default	To specify
zmatrix	Zmatrix tag	yes	-	Identifier for the z-matrix object
index	integer	no	-	Which variable to freeze
indexlist	list of integers	no	-	Which variables to freeze

Description:

z_get_variable_name

Command Line Arguments

Argument	Argument type	Mandatory	Default	To specify
zmatrix	Zmatrix tag	yes	-	Identifier for the z-matrix object
index	integer	yes	-	Variable index

Description: