Command line tool: show_graph

Module	cltools
Description	Input
generate a graph showing how data flows through a PLUMED action set	command line args

Details

show_graph is a tool that takes a plumed input and generates a flowchart showing how data flows through the action set involved.

For example, if we have the following plumed input:

Click on the labels of the actions for more information on what each action computes

d1The DISTANCE action with label d1 calculates the following quantities:
 Quantity   
 Type   
 Description  
d1
scalar
the DISTANCE between this pair of atoms: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=1,2
a1The ANGLE action with label a1 calculates the following quantities:
 Quantity   
 Type   
 Description  
a1
scalar
the ANGLE involving these atoms: ANGLECalculate one or multiple angle/s. More details ATOMSthe list of atoms involved in this collective variable (either 3 or 4 atoms)=1,2,3
t1The TORSION action with label t1 calculates the following quantities:
 Quantity   
 Type   
 Description  
t1
scalar
the TORSION involving these atoms: TORSIONCalculate one or multiple torsional angles. More details ATOMSthe four atoms involved in the torsional angle=1,2,3,4
rThe RESTRAINT action with label r calculates the following quantities:
 Quantity   
 Type   
 Description  
r.bias
scalar
the instantaneous value of the bias potential
r.force2
scalar
the instantaneous value of the squared force due to this bias potential: RESTRAINTAdds harmonic and/or linear restraints on one or more variables. This action has hidden defaults. More details ARGthe values the harmonic restraint acts upon=d1,a1 ATthe position of the restraint=1.0,pi/2 KAPPA specifies that the restraint is harmonic and what the values of the force constants on each of the variables are=100,100
r: RESTRAINTAdds harmonic and/or linear restraints on one or more variables. This action uses the defaults shown here. More details ARGthe values the harmonic restraint acts upon=d1,a1 ATthe position of the restraint=1.0,pi/2 KAPPA specifies that the restraint is harmonic and what the values of the force constants on each of the variables are=100,100  SLOPE specifies that the restraint is linear and what the values of the force constants on each of the variables are=0.0,0.0
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=d1,a1,t1,r.* FILEthe name of the file on which to output these quantities=colvar

We can use the command:

plumed show_graphgenerate a graph showing how data flows through a PLUMED action set This action has hidden defaults. More details --plumed the plumed input that we are generating the graph for plumed.dat

The show_graph action with label plumed calculates somethingplumed show_graphgenerate a graph showing how data flows through a PLUMED action set This action uses the defaults shown here. More details --plumed the plumed input that we are generating the graph for plumed.dat
 --out the dot file containing the graph that has been generated graph.md --natoms the dot file containing the graph that has been generated 1000000 

To generate the following flowchart showing how data passes through these actions during the PLUMED calculation.

flowchart TB 
MD(positions from MD)
Box("label=Box 
 PBC 
")
Box -- Box --> d1
linkStyle 0 stroke:red,color:red;
MD --> d1
linkStyle 1 stroke:violet,color:violet;
d1(["label=d1 
 DISTANCE 
"])
Box -- Box --> a1
linkStyle 2 stroke:red,color:red;
MD --> a1
linkStyle 3 stroke:violet,color:violet;
a1(["label=a1 
 ANGLE 
"])
Box -- Box --> t1
linkStyle 4 stroke:red,color:red;
MD --> t1
linkStyle 5 stroke:violet,color:violet;
t1(["label=t1 
 TORSION 
"])
d1 -- d1 --> r
a1 -- a1 --> r
r(["label=r 
 RESTRAINT 
"])
d1 -- d1 --> 8
a1 -- a1 --> 8
t1 -- t1 --> 8
r -- r.bias --> 8
r -- r.force2 --> 8
8("label=#64;8 
 PRINT
FILE=colvar 
")

Furthermore, if we want to understand how forces on the atoms are calculated from these actions by using the chain rule we can use the following command:

plumed show_graphgenerate a graph showing how data flows through a PLUMED action set This action has hidden defaults. More details --plumed the plumed input that we are generating the graph for plumed.dat --force print a graph that shows how forces are passed through the actions

The show_graph action with label plumed calculates somethingplumed show_graphgenerate a graph showing how data flows through a PLUMED action set This action uses the defaults shown here. More details --plumed the plumed input that we are generating the graph for plumed.dat --force print a graph that shows how forces are passed through the actions
 --out the dot file containing the graph that has been generated graph.md --natoms the dot file containing the graph that has been generated 1000000 

To generate the following flowchart:

flowchart BT 
r(["label=r 
 RESTRAINT 
"])
r -- d1 --> d1
r -- a1 --> a1
a1(["label=a1 
 ANGLE 
"])
d1(["label=d1 
 DISTANCE 
"])
Box("label=Box 
 PBC 
")
d1 -- Box --> Box
linkStyle 2 stroke:red,color:red;
d1 --> MD
linkStyle 3 stroke:violet,color:violet;
a1 -- Box --> Box
linkStyle 4 stroke:red,color:red;
a1 --> MD
linkStyle 5 stroke:violet,color:violet;
MD(positions from MD)

These flowcharts are output in a file called graph.md unless you use the --out option as shown below:

plumed show_graphgenerate a graph showing how data flows through a PLUMED action set This action has hidden defaults. More details --plumed the plumed input that we are generating the graph for plumed.dat --out the dot file containing the graph that has been generated mygraph.md

The show_graph action with label plumed calculates somethingplumed show_graphgenerate a graph showing how data flows through a PLUMED action set This action uses the defaults shown here. More details --plumed the plumed input that we are generating the graph for plumed.dat --out the dot file containing the graph that has been generated mygraph.md
 --natoms the dot file containing the graph that has been generated 1000000 

In this case the flowchart is output to a file called mygraph.md. This file contains the instructions for constructing the flowchart in mermaid flowchart syntax. To construct images similar to those above you can copy and paste the contents of the output graph.md file into this online tool for rendering mermaid diagrams.

If you are writing documentation for PLUMED or tutorials for the plumed tutorials site you can add these diagrams by adding the instruction #MERMAID=value or #MERMAID=force into example inputs. When these options are given inputs are displayed as mermaid diagrams in the final output html.

Syntax

The following table describes the command line options that are available for this tool

Keyword	Description
--help/-h	print this help
--plumed	the plumed input that we are generating the graph for
--out	the dot file containing the graph that has been generated
--natoms	the dot file containing the graph that has been generated
--force	print a graph that shows how forces are passed through the actions