Skip to content

[ZMATRIX]#

The ZMATRIX block defines the structure for which ChemNetworks will search within the trajectory. The Z-matrix defined in any given ZMATRIX block can be used in multiple [GRAPH] blocks. This block can be created multiple times to define multiple search structures.

A Z-matrix is a way of describing a molecular structure using internal coordinates. Rather than specifying absolute positions, each atom is defined relative to previously defined atoms using bond lengths, angles, and dihedral angles.

Each row in a Z-matrix adds one atom. The columns are ordered and represent:

  1. The atom type
  2. The reference atom to which this atom is bonded
  3. The bond length to that reference atom
  4. A second reference atom, forming a three-atom angle
  5. The angle between the three atoms
  6. A third reference atom, forming a four-atom dihedral
  7. The dihedral angle between the four atoms

Bond, angle, and dihedral criteria are sufficient to rigorously define the 3D structure of any molecule with 4 or more atoms. For example, a TIP3P water molecule can be written as:

H
O 1 0.9584
H 2 0.9584 1 104.45

Z-matrices are not limited to describing individual molecules. They can encode any 3D structure, including inter-molecular interactions. For example, a water-water hydrogen bond can be described as:

O
H 1 1.2
O 2 0.9584 1 175

In ChemNetworks, Z-matrix parameters are specified as ranges rather than exact values. This accounts for the variation in bond lengths, angles, and dihedrals that arise from thermal motion and different potential energy surfaces. Atom types and parameter ranges are abstracted into named wildcard variables using $VAR definitions and Z-matrix Commands. For example, the water-water hydrogen bond interaction using this syntax:

[ZMATRIX]
NAME = w-w-hbond

$O = attr atom_type OW
$H = attr atom_type HW1 HW2
$CB = dist 0.0 1.2
$HB = dist 1.2 2.5
$ang = angle 130 181

ROW = $O
ROW = $H 1 $CB
ROW = $O 2 $HB 1 $ang

NAME#

Usage#

NAME = $zmatrix_section_name

Default = zmatrix

User defined name of the ZMATRIX section. Name is required and must be first entry of ZMATRIX section. Referenced by ZMATRIX_SEARCH, ADD.EDGES.ZMATRIX, and related attribute commands to identify this block.

ROW#

Usage#

ROW = $var [$row_# $var [$row_# $var [...]]]

Default = N/A

Defines one row of the Z-matrix. During a Z-matrix search, constraints defined with multiple ROW commands are tested from top to bottom, left to right. Each ROW command attempts to add a new particle to a partial Z-matrix structure. If all constraints defined in all ROW commands within a ZMATRIX block are satisfied, a full structure has been found.

Each ROW command begins with a $var that defines a 1-body Z-matrix constraint. This constraint selects a node to test when building the partial Z-matrix structure. After this 1-body Z-matrix command, pairs of tokens are used to define constraints between the test node and sets of other previously accepted nodes.

As an example, take ROW = $A 3 $B 2 $C 1 $D. This row command represents the addition of an atom requiring four constraints to be met for acceptance:

  1. The 1-body Z-matrix constraint $A (e.g. atom type), must be satisfied for just the test node, here node 4.
  2. The 2-body Z-matrix constraint $B (e.g. distance), between the nodes 4 and 3 must be satisfied.
  3. The 3-body Z-matrix constraint $C (e.g. angle), between nodes 4, 3, and 2, in that order, must be satisfied.
  4. The 4-body Z-matrix constraint $D (e.g. dihedral), between nodes 4, 3, 2, and 1, in that order, must be satisfied.

While typical for linear chain interactions, the $row_# values do not need to be sequential or monotonic. For example, the definition of a metal ligand complex may have ROW commands such as: ROW = $L 1 $d 6 $a90 5 $d90.

$VAR#

Usage#

$VAR = $function_name $args

Default = N/A

Variable definition of a Z-matrix command and its arguments. See Z-matrix Commands for details on the available commands.

$*#

$* is a reserved (cannot be redefined) variable name that unconditionally returns true for whatever column it is placed in. Because $* always returns true, it is useful when a particular N-Body structural criterion is irrelevant.

For example, to match a hydrogen-bond to any atom regardless of the donor atom type:

ROW = $*
ROW = $H 1 $CB
ROW = $* 2 $HB 1 $ang

As another example, sampling a dihedral where the 3-body angles are not relevant:

ROW = $A
ROW = $B 1 $dis
ROW = $C 2 $dis 1 $*
ROW = $D 3 $dis 2 $* 1 $dih

TOTAL#

Usage#

TOTAL = $command_name $args

Default = N/A

Defines an aggregate constraint over all nodes in a completed Z-matrix structure. Unlike ROW constraints which are tested per-row during the search, TOTAL constraints are evaluated after all ROW constraints have been satisfied. If any TOTAL constraint fails, the candidate structure is rejected.

Multiple TOTAL commands can be specified within a single ZMATRIX block. All must pass for the structure to be accepted.

SUM is currently the only available TOTAL command.

Examples#

[ZMATRIX]
NAME = charged-cluster

$A = attr element Na
$B = attr element Cl
$d = dist 0.0 3.5

ROW = $A
ROW = $B 1 $d
ROW = $A 2 $d
TOTAL = SUM charge > 0.0