Z-matrix Commands#

These are the available functions for Z-matrix searches.

attr#

$VAR = attr $attribute_name $attribute_value1 [$attribute_value2 ...]

The attr command is a first column, one-body command which matches true on nodes which have the attribute $attribute_name equal to any of the provided attribute values. Multiple values can be specified to match nodes with any of those values.

Examples#

$A = attr type 0
$B = attr atom_type C
$C = attr element H O N    
$D = attr residue_name WAT SOL TIP3

dist#

$VAR = dist $min_dist $max_dist

The dist command is a second column, two-body command which matches true on pairs of nodes with a Euclidean distance between $min_dist and $max_dist, inclusive. Units are those of the trajectory after scaling by TRAJECTORY.SCALE.

pe_lj#

$VAR = pe_lj $sigma $epsilon [$max_energy [$min_energy]]

The pe_lj command is a second column, two-body command which matches true on pairs of nodes which have a Lennard-Jones (LJ) energy within the specified range. If not specified, the range is from $-\infty$ to 0 energy units. Note that $max_energy (upper bound) is specified before $min_energy (lower bound). The LJ equation is below:

\[V(r) = 4\epsilon(\frac{\sigma^{12}}{r^{12}} - \frac{\sigma^6}{r^6})\]

The user is responsible for the correctness of the units and values of the $sigma and $epsilon parameters. $sigma should have units equal to the position units after being scaled by TRAJECTORY.SCALE. $epsilon should have units equal to the optional $max_energy and $min_energy values.

In an effort to reduce the number of neighbors in the neighbor list, ChemNetworks will calculate the maximum distance along the LJ potential that corresponds to the $max_energy. This distance is then used when creating Verlet neighbor lists.

Solving the LJ equation for r yields twelve roots. Eight of these roots are imaginary. Two more are negative in r. The remaining two roots are valid, and are shown in the equation below, where $max_energy is used in place of $V$. The roots only differ by the sign on the inner square root. Taking the maximum of these two roots provides the distance to be used in the Verlet neighbor listing.

\[ r = \sigma * \sqrt[6]{2\left(\frac{-\epsilon \pm \sqrt{\epsilon\ (V + \epsilon)}}{V}\right)} \]

If $max_energy is zero, then the distance is set to $\infty$. If $max_energy is equal to -$epsilon, the distance is set to $2^{1/6}*$$sigma. If $max_energy is less than -$epsilon, an error is thrown.

Examples#

$P_Xe-Xe = pe_lj 4.1 1.8          # Non-repulsive Xe-Xe interaction
$P_Xe-Xe = pe_lj 4.1 1.8 -0.647   # Slightly more attractive Xe-Xe interaction
$P_Xe-Xe = pe_lj 4.1 1.8 1.0 0.0  # Only repulsive Xe-Xe interaction

angle#

$VAR = angle $min_angle $max_angle

The angle command is a third column, three-body command that returns true on sets of nodes with an angle between $min_angle and $max_angle, inclusive. The angles are in units of degrees. $min_angle must be less than or equal to $max_angle. The computed angle is always between 0 and 180 degrees, so bounds outside this range are accepted but will never match a computed value. Using a bound slightly beyond 0 or 180 (e.g. 181) is a common pattern to ensure that values at exactly 0 or 180 degrees are captured despite floating-point rounding.

Examples#

$A1 = angle 179 181  # Near linear, (181 catches rounding at exactly 180)
$A2 = angle 89 91    # Near right angled
$A3 = angle 60 181   # 60 to 181 degrees
$A4 = angle 0 60     # Narrow angles only

dihedral#

$VAR = dihedral $min_angle $max_angle

The dihedral command is a fourth column, four-body command that returns true on sets of nodes which form a dihedral angle between $min_angle and $max_angle, inclusive. The angles are in units of degrees. The computed dihedral is always between 0 and 180 degrees, as the absolute value of the signed dihedral angle is used. Computed values will never fall outside the 0 to 180 range, but out-of-range bounds are accepted. Using bounds slightly beyond 0 or 180 (e.g. -1 or 181) is a common pattern to ensure values at exactly 0 or 180 degrees are captured despite floating-point rounding.

Examples#

$d1 = dihedral -1  1    # Flat structure (-1 catches rounding at exactly 0)
$d2 = dihedral 89 91    # Orthogonal dihedrals
$d3 = dihedral 179 181  # Anti configuration (181 catches rounding at exactly 180)

SUM#

TOTAL = SUM $attribute_name $operator $value

The SUM command is a TOTAL command which sums a numeric vertex attribute across all nodes in a completed Z-matrix structure and compares the result against $value using $operator. The operator can be any of: >=, \<=, ==, !=, >, or <.

Examples#

TOTAL = SUM charge > 0.0
TOTAL = SUM charge != 0.0
TOTAL = SUM mass <= 100.0
TOTAL = SUM pe < 0.0

Logical Operators#

ChemNetworks provides logical operators for combining and negating other Z-matrix commands. These operators take in command variables (using $VAR, bare commands like dist 0.0 1.2 are not accepted), and return the result of the logical operation.

When logical operators return true, they combine the parameter strings from their successful sub-commands using underscores as separators. These combined parameters are used when writing Z-matrix output files and contain the actual values that matched the criteria.

For example:

$A = attr type 1
$B = attr mol_id 2
$C = or $A $B

$C would return 1_2 in the corresponding slot in the Z-matrix files if both constraints match, or just 1 or 2 if only one matches.

In a more complex and contrived example:

$A = attr atom_type O2
$B = attr mol_type SOL
$C = attr mol_id 1 2 3 4 5 6 7 8 9 10
$D = not $C
$E = all $A $B $D

This could return O2_SOL_35 as one of the matched values.

The logical operators can also be used with other Z-matrix functions. As an example, looking for defects in a crystal structure could be performed by looking for incorrect angles. This can be achieved using:

$A = angle 105 115
$B = not $A

Which would return a single value for the angle, 103, for example.

As another example:

$A = dist 0 1.1
$B = pe_lj 1.0 1.0
$C = and $A $B

Could return 1.03_-0.54442, combining the distance and potential energies into a single pairwise result.

It is possible for logic commands to have duplicate values in the result string if the functions have overlap. For example:

$A = dist 0 1 
$B = dist 0.5 1
$C = and $A $B
$D = or $A $B

$C will always take the form #_#. Because $D uses the or operator, it is possible for it to return the form # or #_#, depending on whether both $A and $B pass (0.5 <= dist <= 1) or just the more permissive $A.

All functions used within a logical operator must have matching particle counts. For example, you cannot combine a two-body function like dist (which operates on pairs of nodes) with a three-body function like angle (which operates on triplets of nodes).

and#

Returns true if both supplied command variables are true.

$OP = and $A $B

or#

Returns true if either (or both) of the supplied command variables are true.

$OP = or $A $B

xor#

Returns true if exactly one of the two supplied command variables is true.

$OP = xor $A $B

not#

Returns the opposite boolean of the supplied command variable.

$OP = not $A

any#

Returns true if any of the supplied command variables are true.

$OP = any $A $B $C ...

all#

Returns true if all the supplied command variables are true.

$OP = all $A $B $C ...

none#

Returns true if none of the supplied command variables are true.

$OP = none $A $B $C ...