[GRAPH]#

The GRAPH block collects the trajectory and Z-matrix search structures, performs the structure search, and creates the graph network based on the Z-matrix search. Analyses may be performed to modify the graph edges/nodes, or to add simple per-node/edge analyses as accessible attributes. Finally, this block can write the node, Z-matrix, and edge definitions to their corresponding files on a frame by frame basis.

Command Ordering#

Commands within a GRAPH block are executed in the order they appear. Some commands depend on others having been run first. The required ordering is:

ADD.NODES.* should come before any edge, attribute, analysis, or write commands.
ZMATRIX_SEARCH should come before ADD.EDGES.ZMATRIX, ADD.ATTRIBUTE.*.ZMATRIX, and WRITE.ZMATRIX for the same Z-matrix.
ADD.EDGES.* should come before edge attribute commands (ADD.ATTRIBUTE.EDGE.*).
ADD.GRAPH copies a previously defined graph in its entirety. The source graph's [GRAPH] block must appear before the block that uses ADD.GRAPH. No ADD.NODES.* or ADD.EDGES.* commands are needed when using ADD.GRAPH.
ANALYSIS commands run in the order listed. An analysis that creates an attribute (e.g. degree) must appear before any write command that outputs that attribute.
WRITE.* commands should appear last, after the graph is fully constructed and analyzed.

NAME#

Usage#

NAME = $graph_section_name

Default = graph

User defined name of the GRAPH section. Name is required and must be first entry of GRAPH section. Used in default output directory paths (e.g. ./grph_$graphname/).

DIRECTED#

Usage#

DIRECTED = true $to_directed_mode

DIRECTED = false $to_undirected_mode [$attr:method ...] [$default_comb]

Default = N/A

All graphs are undirected on creation. This command converts the graph from undirected to directed, or vice versa. It may be specified multiple times within a [GRAPH] block to toggle the directionality.

When converting to undirected (false), edges may be merged, and the edge attribute combination may be specified using the standard Attribute Combination syntax. Attribute combination is not applicable when converting to directed (true).

As an example, DIRECTED = false collapse weight:sum distance:mean ignore converts all edges from directed to undirected using the collapse mode, sums the weight attributes, averages the distance attributes, and ignores (leaves blank) all other attributes.

Undirected To Directed Edge Merging Modes#

arbitrary (default) : An arbitrarily directed edge is created for each undirected edge.
acyclic : Each undirected edge is converted to a directed edge oriented from a lower index to a higher index one.
random : Each undirected edge is converted to a randomly oriented directed edge.
mutual : Two directed edges are created for each undirected edge.

Directed To Undirected Edge Merging Modes#

collapse (default) : One undirected edge is created for each directed edge, without creating multi-edges.
each : An undirected edge is created for each directed edge. Two undirected edges are added for each mutual edge.
mutual : An undirected edge is created only for each pair of mutual edges. Non-mutual edges are lost.

ADD.NODES.TRAJECTORY#

Usage#

ADD.NODES.TRAJECTORY = $trajectory_section_name

Default = N/A

Name of the TRAJECTORY block to load into this graph. All atoms at the current timestep are added as nodes, with their trajectory attributes available as node attributes.

ADD.NODES.FROM_FILE#

Usage#

ADD.NODES.FROM_FILE = $file_name

Default = N/A

Read nodes and node attributes from a node file (.nds). The file name should be specified without the timestep suffix or file extension. For example, if the files are named nodes.0.nds, nodes.1.nds, etc., use ADD.NODES.FROM_FILE = nodes.

See WRITE.NODES for the node file format specification.

ADD.EDGES.FROM_FILE#

Usage#

ADD.EDGES.FROM_FILE = $file_name

Default = N/A

Read edges, node attributes, and edge attributes from an edge file (.edg). The file name should be specified without the timestep suffix or file extension. For example, if the files are named edges.0.edg, edges.1.edg, etc., use ADD.EDGES.FROM_FILE = edges.

Reading from an edge file automatically creates nodes and populates both node and edge attributes found in the file.

See WRITE.EDGES for the edge file format specification.

ADD.EDGES.ZMATRIX#

Usage#

ADD.EDGES.ZMATRIX = $zmatrix_section_name $row_i $row_j

Default = N/A

For all sets of nodes meeting the Z-matrix template, adds edges between the nodes at 1-indexed row numbers $row_i and $row_j. A ZMATRIX_SEARCH for the same $zmatrix_section_name must appear before this command.

ADD.GRAPH#

Usage#

ADD.GRAPH = $graph_section_name

Default = N/A

Deep copy all nodes, edges, and their attributes from a previously defined graph into this graph block. The source $graph_section_name must refer to the NAME of a [GRAPH] block that appears earlier in the input file, so that it is fully constructed before the copy occurs.

No ADD.NODES.* or ADD.EDGES.* commands are needed when using ADD.GRAPH, as the copied graph already contains the full node and edge structure of the source.

ADD.ATTRIBUTE.NODE.NODE#

Usage#

ADD.ATTRIBUTE.NODE.NODE = $attr_name $attr_value $new_attr_name $new_attr_value

Default = N/A

For every node where the existing attribute $attr_name equals $attr_value, set a new attribute $new_attr_name to $new_attr_value. Nodes that do not match are unaffected. This is commonly used to rename atom types, e.g. ADD.ATTRIBUTE.NODE.NODE = atom_type OW atom_type O renames all OW atoms to O.

ADD.ATTRIBUTE.NODE.ZMATRIX#

Usage#

ADD.ATTRIBUTE.NODE.ZMATRIX = $zmatrix_section_name $new_attr_name

Default = N/A

For every node found in a match of the named Z-matrix template, set the attribute $new_attr_name to the value $zmatrix_section_name. For example, ADD.ATTRIBUTE.NODE.ZMATRIX = wat_wat hbond_member sets the hbond_member attribute to "wat_wat" on every node participating in a wat_wat match.

ADD.ATTRIBUTE.EDGE.EDGE#

Usage#

ADD.ATTRIBUTE.EDGE.EDGE =

Default = N/A

Calculate edge attribute for all edges in the graph. Limited to the available pairwise node calculations dist and inv_dist.

Periodic boundary conditions are applied via the minimum image convention when PBC.DIM is set.

ADD.ATTRIBUTE.EDGE.ZMATRIX#

Usage#

ADD.ATTRIBUTE.EDGE.ZMATRIX = $zmatrix_section_name $attr_name $row $variable

Default = N/A

Add a new edge attribute to edges created by ADD.EDGES.ZMATRIX, using a calculated value from the Z-matrix search. The $row is a 1-indexed row number of the Z-matrix, and $variable is a variable name (e.g. $D0) defined in the Z-matrix. The calculated value of $variable at $row is set as the $attr_name attribute on all edges for each Z-matrix match.

As multiple ZMATRIX_SEARCH commands can be performed, it is possible that the resulting edge list will not have the new attribute defined for all edges. This means that the .edg files may be ragged arrays of data. If you parse the .edg files using tab delimiters, there will be some empty entries, but otherwise no issues.

ANALYSIS#

Usage#

ANALYSIS = $method $parameters

Default = N/A

Perform the analysis method with the given set of parameters. Analyses operate on the graph after it has been constructed and can modify its structure (e.g. merging nodes, filtering edges) or compute graph-theoretic properties (e.g. degree, betweenness). See the Analysis page for the full list of available methods.

ZMATRIX_SEARCH#

Usage#

ZMATRIX_SEARCH = $zmatrix_section_name

Default = N/A

Search through the trajectory for all instances of the structure defined in the named ZMATRIX block.

WRITE.ZMATRIX#

Usage#

WRITE.ZMATRIX = $zmatrix_section_name [$file_name]

Default = "" ./grph_$graphname/zmt/<zmatrix_section_name>_$timestep.zmt

Write found Z-matrix structures and calculated parameters to a file. The file name will follow the standard File Naming Convention.

Z-matrix File Format#

Z-matrix files use a tab-separated format. The first line contains the timestep. The remaining content consists of structure matches separated by blank lines. Each match contains one line per Z-matrix row, mirroring the structure of the original Z-matrix definition.

Each line begins with the matched node index and the result of the row's one-body command (e.g. the atom type). Subsequent columns alternate between a reference node index and the calculated value of the corresponding N-body command (distance, angle, or dihedral). The columns follow the same order as the constraints in the ROW definition.

If the Z-matrix block defines TOTAL commands, their results are appended after the row data for each match. Each TOTAL line contains the keyword TOTAL, the command name, the command description, and the computed result. If no TOTAL commands are specified, no TOTAL lines are written.

TIMESTEP    $timestep
<node>  <1-body_value>
<node>  <1-body_value>  <ref_node>  <2-body_value>
<node>  <1-body_value>  <ref_node>  <2-body_value>  <ref_node>  <3-body_value>
TOTAL   <command_name>  <description>   <result>

<node>  <1-body_value>
<node>  <1-body_value>  <ref_node>  <2-body_value>
<node>  <1-body_value>  <ref_node>  <2-body_value>  <ref_node>  <3-body_value>
TOTAL   <command_name>  <description>   <result>
...

For example, a three-row water-water hydrogen bond Z-matrix with a (here, redundant) charge neutrality constraint:

ROW = $O
ROW = $H 1 $HB
ROW = $O 2 $CB 1 $A
TOTAL = SUM q == 0.0

produces matches like:

TIMESTEP    0
30  O
2359    H   30  2.470298
2358    O   2359    0.976419    30  152.564861
TOTAL   SUM q   0.000000

42  O
490 H   42  2.216309
489 O   490 0.976838    42  169.568388
TOTAL   SUM q   0.000000
...

WRITE.NODES#

Usage#

WRITE.NODES = < true | $file_name >

Default = N/A (not written). Default path when true: ./grph_$graphname/nds/$graphname

Write all nodes to file. The file name will follow the standard File Naming Convention.

Node File Format#

Node files use a tab-separated format. The first line contains the timestep. The second line is a header row starting with i (node index) followed by attribute names specified by WRITE.NODES.ATTRIBUTES. Subsequent lines contain the node index followed by attribute values.

TIMESTEP    $timestep
i   <attr_1>    <attr_2>    ...
<node_index>    <attr_value>    <attr_value>    ...
<node_index>    <attr_value>    <attr_value>    ...
...

WRITE.NODES.ATTRIBUTES#

Usage#

WRITE.NODES.ATTRIBUTES = $attr_name [$attr_name ...]

Default = ""

Writes the given node attributes to the nodes file alongside the node index i. If set to *, all nodes attributes will be written.

WRITE.EDGES#

Usage#

WRITE.EDGES = < true | $file_name >

Default = N/A (not written). Default path when true: ./grph_$graphname/edg/$graphname

Write all edges to file. If true is specified, use the default naming scheme. The file name will follow the standard File Naming Convention.

Edge File Format#

Edge files use a tab-separated format. The first line contains the timestep. The second line is a header row containing i, followed by node attribute names for the source node (specified by WRITE.EDGES.ATTRIBUTES.NODES), and j followed by the same node attribute names for the destination node. After the node information are the edge attribute names, specified by WRITE.EDGES.ATTRIBUTES.EDGES.

Subsequent lines contain the node and edge data, with node indices and their corresponding attribute values, followed by edge attribute values.

TIMESTEP    $timestep
i   <node_attr_1>   ... j   <node_attr_1>   ... <edge_attr_1>   ...
<from_node> <value> ... <to_node>   <value> ... <value> ...
<from_node> <value> ... <to_node>   <value> ... <value> ...
...

WRITE.EDGES.ATTRIBUTES.NODES#

Usage#

WRITE.EDGES.ATTRIBUTES.NODES = $attr_name [$attr_name ...]

Default = ""

Writes the given node attributes to the edges file along the node indices i and j. If set to *, all nodes attributes will be written.

WRITE.EDGES.ATTRIBUTES.EDGES#

Usage#

WRITE.EDGES.ATTRIBUTES.EDGES = $attr_name [$attr_name ...]

Default = ""

Writes the given edge attributes to the edges file. If set to *, all edge attributes will be written.

WRITE.LAMMPS#

Usage#

WRITE.LAMMPS = < true | $file_name >

Default = N/A (not written). Default path when true: ./grph_$graphname/lmp/$graphname

Write the graph to a LAMMPS data file. If true is specified, use the default naming scheme. The file name will follow the standard File Naming Convention.

Atom names, residue IDs, and bond types are resolved using the standard Attribute Resolution order.

This is the recommended format for visualizing ChemNetworks graphs in OVITO.

WRITE.MOL2#

Usage#

WRITE.MOL2 = < true | $file_name >

Default = N/A (not written). Default path when true: ./grph_$graphname/mol2/$graphname

Write the graph to a MOL2 data file. If true is specified, use the default naming scheme. The file name will follow the standard File Naming Convention.

Atom names, residue names, residue IDs, and bond types are resolved using the standard Attribute Resolution order.

This is the recommended format for visualizing ChemNetworks graphs in VMD.

WRITE.PDB#

Usage#

WRITE.PDB = < true | $file_name >

Default = N/A (not written). Default path when true: ./grph_$graphname/pdb/$graphname

Write the graph to a PDB file. If true is specified, use the default naming scheme. The file name will follow the standard File Naming Convention.

PDB files use the standard column format with HETATM records for nodes and CONECT records for edges. Atom names, residue names, and residue IDs are resolved using the standard Attribute Resolution order.

The PDB format has a 5-column limit for atom indices, meaning it cannot properly count past 99,999. Requesting PDBs for systems with more than 99,999 atoms will print a warning and may generate files with overflowed serial numbers. For large systems, consider using WRITE.LAMMPS or WRITE.MOL2 instead.