Input File Tutorial#
This tutorial explains in detail the
water-licl_lammpstrj example input file,
covering the reasoning behind each command and how the blocks work together to produce a hydrogen bonding / ion
interaction graph.
The System#
The trajectory contains a box of 8,960 atoms: water molecules with dissolved lithium and chloride ions. Four atom types are present:
| Type | Element |
|---|---|
| 1 | O |
| 2 | H |
| 3 | Li |
| 4 | Cl |
The trajectory is stored in LAMMPS dump format (water_li_cl.lammpstrj) with 10 timesteps. Each frame provides the
atom id, type, x, y, and z attributes:
ITEM: TIMESTEP
0
ITEM: NUMBER OF ATOMS
8960
ITEM: BOX BOUNDS pp pp pp
-0.494509 49.0455
-0.491493 49.0485
-0.500504 49.0395
ITEM: ATOMS id type x y z
1 1 27.766 41.143 30.465
2 2 28.398 40.617 30.994
3 2 27.649 40.589 29.67
...
The goal is to build a graph that captures four types of interactions in this system: water-water hydrogen bonds, lithium-chloride ion pairs, chloride-water interactions, and lithium-water interactions.
SETTINGS Block#
TIMESTEPS = 0 9 specifies the range of timesteps to analyze, using the
default value of the stride, 1. The trajectory contains timesteps 0 through 9, so this processes all 10 frames.
TRAJECTORY Block#
[TRAJECTORY]
NAME = water_li_cl_system
FILE = ./water_li_cl.lammpstrj
TYPE = lammpstrj
PBC.DIM = read
NAME = water_li_cl_system assigns an identifier that is referenced later by the
GRAPH.ADD.NODES.TRAJECTORY command.
FILE = ./water_li_cl.lammpstrj points to the trajectory file, relative to the
working directory.
TYPE = lammpstrj tells ChemNetworks to parse the file as a LAMMPS dump. All
columns in the ITEM: ATOMS header are read as node attributes.
PBC.DIM = read reads the simulation box dimensions directly from the trajectory
file. LAMMPS trajectories include box bounds in the ITEM: BOX BOUNDS header of each frame. This is equivalent to
manually specifying the six boundary values, but avoids hardcoding them. With
PBC.DIM = read set, ChemNetworks applies the minimum image convention for
all distance calculations, correctly handling atoms near periodic boundaries without any additional configuration.
ZMATRIX Blocks#
This example defines four separate ZMATRIX blocks, one for each type of interaction. Each block defines a structural template that ChemNetworks searches for in the graph.
Water-Water Hydrogen Bond#
[ZMATRIX]
NAME = wat_wat
ROW = $O
ROW = $H 1 $HB
ROW = $O 2 $CB 1 $A
$O = attr type 1
$H = attr type 2
$HB = dist 1.0 2.5
$CB = dist 0.0 1.0
$A = angle 145.0 185.0
This is a three-row Z-matrix describing a hydrogen bond between two water molecules. Reading the rows:
- Row 1 defines the first atom: an oxygen (
$O, type 1). - Row 2 defines a hydrogen (
$H, type 2), bonded to row 1 with distance$HB(1.0 to 2.5 angstroms). This is the hydrogen bond distance between the donor hydrogen and the acceptor oxygen. - Row 3 defines a second oxygen (
$O, type 1), bonded to row 2 with distance$CB(0.0 to 1.0 angstroms) and forming an angle$A(145 to 185 degrees) with rows 1 and 2. The short distance is the covalent O-H bond, and the angle constraint ensures the hydrogen bond is roughly linear.
The $VAR = ... lines define what each variable means.
attr type 1 matches nodes where the type attribute equals 1.
dist 0.0 1.0 matches pairs of nodes within that distance range.
angle 145.0 185.0 matches triplets of nodes forming an angle within that
range. See Z-matrix Commands for all available commands.
Lithium-Chloride Ion Pair#
[ZMATRIX]
NAME = li_cl
ROW = $LI
ROW = $CL 1 $D
$LI = attr type 3
$CL = attr type 4
$D = dist 1.5 3.26
A two-row Z-matrix matching lithium (type 3) and chloride (type 4) pairs within 1.5 to 3.26 angstroms. Two-row Z-matrices only require a distance constraint.
Lithium-Water and Chloride-Water Coordination#
[ZMATRIX]
NAME = li_wat
ROW = $LI
ROW = $O 1 $D
$LI = attr type 3
$O = attr type 1
$D = dist 0.0 3.0
[ZMATRIX]
NAME = cl_wat
ROW = $CL
ROW = $H 1 $D
$CL = attr type 4
$H = attr type 2
$D = dist 0.0 3.0
Two more two-row Z-matrices capturing ion-water interactions. li_wat matches lithium ions near water oxygens, while
cl_wat matches chloride ions near water hydrogens. Both use a 3.0 angstrom cutoff.
GRAPH Block#
[GRAPH]
NAME = OH
ADD.NODES.TRAJECTORY = water_li_cl_system
ZMATRIX_SEARCH = wat_wat
ZMATRIX_SEARCH = li_cl
ZMATRIX_SEARCH = li_wat
ZMATRIX_SEARCH = cl_wat
ADD.EDGES.ZMATRIX = wat_wat 2 1
ADD.EDGES.ZMATRIX = li_cl 2 1
ADD.EDGES.ZMATRIX = li_wat 2 1
ADD.EDGES.ZMATRIX = cl_wat 2 1
ADD.ATTRIBUTE.EDGE.EDGE = dist
ADD.NODES.TRAJECTORY = water_li_cl_system populates the graph with all
atoms from the trajectory defined earlier. Each atom becomes a node with its trajectory attributes (id, type, x,
y, z).
The four ZMATRIX_SEARCH commands run each structural template against the
graph. For every set of nodes that matches a Z-matrix template, ChemNetworks records the match and its calculated
parameters (distances, angles).
The four ADD.EDGES.ZMATRIX commands create edges from those search results.
The syntax ADD.EDGES.ZMATRIX = wat_wat 2 1 means: for every match of the wat_wat template, add an edge between the
node at row 2 and the node at row 1. In the water-water case, this connects the donor hydrogen (row 2) to the acceptor
oxygen (row 1).
ADD.ATTRIBUTE.EDGE.EDGE = dist calculates the Euclidean distance
between connected nodes and stores it as the dist edge attribute. This enables writing the distance values to the
output files.
GRAPH.WRITE Sub-Block#
[GRAPH.WRITE]
EDGES = ./edg_files/edges
EDGES.ATTRIBUTES.EDGES = dist
EDGES.ATTRIBUTES.NODES = id type
NODES = ./nds_files/nodes
NODES.ATTRIBUTES = id type x y z
ZMATRIX = wat_wat ./zmt_files/wat_wat
ZMATRIX = li_cl ./zmt_files/li_cl
ZMATRIX = li_wat ./zmt_files/li_wat
ZMATRIX = cl_wat ./zmt_files/cl_wat
The [GRAPH.WRITE] header is a sub-block of
[GRAPH]. Writing EDGES = ./edg_files/edges here is equivalent to writing
WRITE.EDGES = ./edg_files/edges directly under [GRAPH]. The sub-block syntax reduces
repetition when multiple write commands share the WRITE. prefix.
EDGES = ./edg_files/edges writes edge files to ./edg_files/edges.0.edg,
./edg_files/edges.1.edg, etc. EDGES.ATTRIBUTES.EDGES = dist
includes the dist edge attribute in each edge file.
EDGES.ATTRIBUTES.NODES = id type includes the id and type
node attributes for both endpoints of each edge.
NODES = ./nds_files/nodes writes node files with all graph nodes.
NODES.ATTRIBUTES = id type x y z includes these five attributes per
node.
The four ZMATRIX lines write the Z-matrix search results for each interaction
type to separate files. Each file contains the matched atom indices and calculated parameter values (distances, angles)
for every match found at each timestep.
Running the Example#
From the example directory:
This produces the following output structure: