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.

Values are compared in the attribute's stored type: numeric attributes (such as those produced by degree, betweenness, or steinhardt) are compared numerically, boolean attributes against true or false, and all other attributes as strings. Comparisons are done through checking equality, thus floating point values (or continuous values) may fail to match properly due to machine precision errors.

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 and may be negative. Both bounds must lie within [-180, 180].

The sign distinguishes the two enantiomeric configurations: looking down the central j-k bond, a positive dihedral twists clockwise (the l below goes into the page) and a negative dihedral twists counter-clockwise (the l below comes out of the page).

i         l
 \       /
  j --- k

If $min_angle <= $max_angle, the range is the standard inclusive interval. If $min_angle > $max_angle, the range wraps through +/-180: a dihedral matches when it is >= $min_angle OR <= $max_angle. This makes it natural to write near-trans ranges as a single command that crosses the +/-180 seam, since +180 and -180 describe the same physical configuration but the computed value can land on either endpoint depending on floating-point sign.

Examples#

$d1 = dihedral -1  1     # Near-cis (signed range spanning zero)
$d2 = dihedral 89 91     # Right-handed orthogonal dihedrals only
$d3 = dihedral 175 -175  # Anti configuration (wraps through +/-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

not cannot wrap two-body constraints (dist, pe_lj) because the neighbor-list search would produce no candidates outside the wrapped range. For example, replace not dist 0 1 with dist 1 999 (using whatever upper bound is appropriate for your system). not works as expected for one-body constraints (attr) and three-or-more-body constraints (angle, dihedral). The same restriction applies to none.

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 ...

none cannot wrap two-body constraints (dist, pe_lj) for the same reason as not: the neighbor-list search only enumerates candidate pairs within the union of the wrapped ranges, so none silently misses every pair outside that union (typically most of the simulation box). Express the inverted bounds explicitly instead. none works as expected for one-body and three-or-more-body constraints.