Action: PIV

Module	piv
Description	Usage
Calculates the PIV-distance.
output value	type
the PIV-distance	scalar

Details and examples

Calculates the PIV-distance.

PIV distance is the squared Cartesian distance between the PIV associated to the configuration of the system during the dynamics and a reference configuration provided as input (PDB file format). PIV can be used together with FUNCPATHMSD to define a path in the PIV space.

Examples

The following example calculates PIV-distances from three reference configurations in Ref1.pdb, Ref2.pdb and Ref3.pdb and prints the results in a file named colvar. Three atoms (PIVATOMS=3) with names (pdb file) A B and C are used to construct the PIV and all PIV blocks (AA, BB, CC, AB, AC, BC) are considered. SFACTOR is a scaling factor that multiplies the contribution to the PIV-distance given by the single PIV block. NLIST sets the use of neighbor lists for calculating atom-atom distances. The SWITCH keyword specifies the parameters of the switching function that transforms atom-atom distances. SORT=1 means that the PIV block elements are sorted (SORT=0 no sorting.) Values for SORT, SFACTOR and the neighbor list parameters have to be specified for each block. The order is the following: AA,BB,CC,AB,AC,BC. If ONLYDIRECT (ONLYCROSS) is used the order is AA,BB,CC (AB,AC,BC). The sorting operation within each PIV block is performed using the counting sort algorithm, PRECISION specifies the size of the counting array.

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

PIVCalculates the PIV-distance. More details ...
LABELa label for the action so that its output can be referenced in the input to other actions=Pivd1
PRECISIONthe precision for approximating reals with integers in sorting=1000
NLIST Use a neighbor list for distance calculations
REF_FILEPDB file name that contains the ith reference structure=Ref1.pdb
PIVATOMSNumber of atoms to use for PIV=3
ATOMTYPESThe atom types to use for PIV=A,B,C
SFACTORScale the PIV-distance by such block-specific factor=0.3,0.5,1.0,0.2,0.2,0.2
SORTWhether to sort or not the PIV block=1,1,1,1,1,1
SWITCH1The switching functions parameter={RATIONAL R_0=0.6 MM=12 NN=4}
SWITCH2The switching functions parameter={RATIONAL R_0=0.4 MM=10 NN=5}
SWITCH3The switching functions parameter={RATIONAL R_0=0.4 MM=10 NN=5}
SWITCH4The switching functions parameter={RATIONAL R_0=0.5 MM=12 NN=6}
SWITCH5The switching functions parameter={RATIONAL R_0=0.5 MM=12 NN=6}
SWITCH6The switching functions parameter={RATIONAL R_0=0.5 MM=12 NN=6}
NL_CUTOFFNeighbor lists cutoff=0.8,0.6,0.6,0.7,0.7,0.7
NL_STRIDEUpdate neighbor lists every NL_STRIDE steps=10,10,10,10,10,10
NL_SKINThe maximum atom displacement tolerated for the neighbor lists update=0.1,0.1,0.1,0.1,0.1,0.1
... PIV
The PIV action with label Pivd1 calculates the following quantities:
 Quantity   
 Description  
Pivd1.value
the PIV-distancePIVCalculates the PIV-distance. More details ...
LABELa label for the action so that its output can be referenced in the input to other actions=Pivd2
PRECISIONthe precision for approximating reals with integers in sorting=1000
NLIST Use a neighbor list for distance calculations
REF_FILEPDB file name that contains the ith reference structure=Ref2.pdb
PIVATOMSNumber of atoms to use for PIV=3
ATOMTYPESThe atom types to use for PIV=A,B,C
SFACTORScale the PIV-distance by such block-specific factor=0.3,0.5,1.0,0.2,0.2,0.2
SORTWhether to sort or not the PIV block=1,1,1,1,1,1
SWITCH1The switching functions parameter={RATIONAL R_0=0.6 MM=12 NN=4}
SWITCH2The switching functions parameter={RATIONAL R_0=0.4 MM=10 NN=5}
SWITCH3The switching functions parameter={RATIONAL R_0=0.4 MM=10 NN=5}
SWITCH4The switching functions parameter={RATIONAL R_0=0.5 MM=12 NN=6}
SWITCH5The switching functions parameter={RATIONAL R_0=0.5 MM=12 NN=6}
SWITCH6The switching functions parameter={RATIONAL R_0=0.5 MM=12 NN=6}
NL_CUTOFFNeighbor lists cutoff=0.8,0.6,0.6,0.7,0.7,0.7
NL_STRIDEUpdate neighbor lists every NL_STRIDE steps=10,10,10,10,10,10
NL_SKINThe maximum atom displacement tolerated for the neighbor lists update=0.1,0.1,0.1,0.1,0.1,0.1
... PIV
The PIV action with label Pivd2 calculates the following quantities:
 Quantity   
 Description  
Pivd2.value
the PIV-distancePIVCalculates the PIV-distance. More details ...
LABELa label for the action so that its output can be referenced in the input to other actions=Pivd3
PRECISIONthe precision for approximating reals with integers in sorting=1000
NLIST Use a neighbor list for distance calculations
REF_FILEPDB file name that contains the ith reference structure=Ref3.pdb
PIVATOMSNumber of atoms to use for PIV=3
ATOMTYPESThe atom types to use for PIV=A,B,C
SFACTORScale the PIV-distance by such block-specific factor=0.3,0.5,1.0,0.2,0.2,0.2
SORTWhether to sort or not the PIV block=1,1,1,1,1,1
SWITCH1The switching functions parameter={RATIONAL R_0=0.6 MM=12 NN=4}
SWITCH2The switching functions parameter={RATIONAL R_0=0.4 MM=10 NN=5}
SWITCH3The switching functions parameter={RATIONAL R_0=0.4 MM=10 NN=5}
SWITCH4The switching functions parameter={RATIONAL R_0=0.5 MM=12 NN=6}
SWITCH5The switching functions parameter={RATIONAL R_0=0.5 MM=12 NN=6}
SWITCH6The switching functions parameter={RATIONAL R_0=0.5 MM=12 NN=6}
NL_CUTOFFNeighbor lists cutoff=0.8,0.6,0.6,0.7,0.7,0.7
NL_STRIDEUpdate neighbor lists every NL_STRIDE steps=10,10,10,10,10,10
NL_SKINThe maximum atom displacement tolerated for the neighbor lists update=0.1,0.1,0.1,0.1,0.1,0.1
... PIV

The PIV action with label Pivd3 calculates the following quantities:
 Quantity   
 Description  
Pivd3.value
the PIV-distancePRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=Pivd1,Pivd2,Pivd3 FILEthe name of the file on which to output these quantities=colvar

WARNING: Both the "CRYST" and "ATOM" lines of the PDB files must conform precisely to the official pdb format, including the width of each alphanumerical field:

CRYST1   31.028   36.957   23.143  89.93  92.31  89.99 P 1           1
ATOM      1  OW1 wate    1      15.630  19.750   1.520  1.00  0.00

In each pdb frame, atoms must be numbered in the same order and with the same element symbol as in the input of the MD program.

The following example calculates the PIV-distances from two reference configurations Ref1.pdb and Ref2.pdb and uses PIV-distances to define a Path Collective Variable (FUNCPATHMSD) with only two references (Ref1.pdb and Ref2.pdb). With the VOLUME keyword one scales the atom-atom distances by the cubic root of the ratio between the specified value and the box volume of the initial step of the trajectory file.

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

PIVCalculates the PIV-distance. More details ...
LABELa label for the action so that its output can be referenced in the input to other actions=c1
PRECISIONthe precision for approximating reals with integers in sorting=1000
VOLUMEScale atom-atom distances by the cubic root of the cell volume=12.15
NLIST Use a neighbor list for distance calculations
REF_FILEPDB file name that contains the ith reference structure=Ref1.pdb
PIVATOMSNumber of atoms to use for PIV=2
ATOMTYPESThe atom types to use for PIV=A,B
ONLYDIRECT Use only direct-terms (A-A, B-B, C-C, 
SFACTORScale the PIV-distance by such block-specific factor=1.0,0.2
SORTWhether to sort or not the PIV block=1,1
SWITCH1The switching functions parameter={RATIONAL R_0=0.6 MM=12 NN=4}
SWITCH2The switching functions parameter={RATIONAL R_0=0.5 MM=10 NN=5}
NL_CUTOFFNeighbor lists cutoff=1.2,1.2
NL_STRIDEUpdate neighbor lists every NL_STRIDE steps=10,10
NL_SKINThe maximum atom displacement tolerated for the neighbor lists update=0.1,0.1
... PIV
The PIV action with label c1 calculates the following quantities:
 Quantity   
 Description  
c1.value
the PIV-distancePIVCalculates the PIV-distance. More details ...
LABELa label for the action so that its output can be referenced in the input to other actions=c2
PRECISIONthe precision for approximating reals with integers in sorting=1000
VOLUMEScale atom-atom distances by the cubic root of the cell volume=12.15
NLIST Use a neighbor list for distance calculations
REF_FILEPDB file name that contains the ith reference structure=Ref2.pdb
PIVATOMSNumber of atoms to use for PIV=2
ATOMTYPESThe atom types to use for PIV=A,B
ONLYDIRECT Use only direct-terms (A-A, B-B, C-C, 
SFACTORScale the PIV-distance by such block-specific factor=1.0,0.2
SORTWhether to sort or not the PIV block=1,1
SWITCH1The switching functions parameter={RATIONAL R_0=0.6 MM=12 NN=4}
SWITCH2The switching functions parameter={RATIONAL R_0=0.4 MM=10 NN=5}
NL_CUTOFFNeighbor lists cutoff=1.2,1.2
NL_STRIDEUpdate neighbor lists every NL_STRIDE steps=10,10
NL_SKINThe maximum atom displacement tolerated for the neighbor lists update=0.1,0.1
... PIV

The PIV action with label c2 calculates the following quantities:
 Quantity   
 Description  
c2.value
the PIV-distancep1: FUNCPATHMSDThis function calculates path collective variables. More details ARGthe labels of the values from which the function is calculated=c1,c2 LAMBDAthe lambda parameter is needed for smoothing, is in the units of plumed=0.180338
The FUNCPATHMSD action with label p1 calculates the following quantities:
 Quantity   
 Description  
p1.s
the position on the path
p1.z
the distance from the pathMETADUsed to performed metadynamics on one or more collective variables. More details ARGthe labels of the scalars on which the bias will act=p1.s,p1.z SIGMAthe widths of the Gaussian hills=0.01,0.2 HEIGHTthe heights of the Gaussian hills=0.8 PACEthe frequency for hill addition=500   LABELa label for the action so that its output can be referenced in the input to other actions=res
The METAD action with label res calculates the following quantities:
 Quantity   
 Description  
res.bias
the instantaneous value of the bias potentialPRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=c1,c2,p1.s,p1.z,res.bias STRIDE the frequency with which the quantities of interest should be output=500  FILEthe name of the file on which to output these quantities=colvar FMT the format that should be used to output real numbers=%15.6f

When using PIV please cite the papers from the reference section below.

Full list of keywords

The following table describes the keywords and options that can be used with this action

Keyword	Type	Default	Description
SWITCH	compulsory	none	The switching functions parameter
PRECISION	compulsory	none	the precision for approximating reals with integers in sorting
REF_FILE	compulsory	none	PDB file name that contains the ith reference structure
PIVATOMS	compulsory	none	Number of atoms to use for PIV
SORT	compulsory	none	Whether to sort or not the PIV block
ATOMTYPES	compulsory	none	The atom types to use for PIV
NUMERICAL_DERIVATIVESThis keyword do not have examples	optional	false	calculate the derivatives for these quantities numerically
NOPBCThis keyword do not have examples	optional	false	ignore the periodic boundary conditions when calculating distances
SFACTOR	optional	not used	Scale the PIV-distance by such block-specific factor
VOLUME	optional	not used	Scale atom-atom distances by the cubic root of the cell volume
UPDATEPIVThis keyword do not have examples	optional	not used	Frequency (in steps) at which the PIV is updated
TESTThis keyword do not have examples	optional	false	Print the actual and reference PIV and exit
COMThis keyword do not have examples	optional	false	Use centers of mass of groups of atoms instead of atoms as specified in the Pdb file
ONLYCROSSThis keyword do not have examples	optional	false	Use only cross-terms (A-B, A-C, B-C,
ONLYDIRECT	optional	false	Use only direct-terms (A-A, B-B, C-C,
DERIVATIVESThis keyword do not have examples	optional	false	Activate the calculation of the PIV for every class (needed for numerical derivatives)
NLIST	optional	false	Use a neighbor list for distance calculations
SERIALThis keyword do not have examples	optional	false	Perform the calculation in serial - for debug purpose
TIMERThis keyword do not have examples	optional	false	Perform timing analysis on heavy loops
NL_CUTOFF	optional	not used	Neighbor lists cutoff
NL_STRIDE	optional	not used	Update neighbor lists every NL_STRIDE steps
NL_SKIN	optional	not used	The maximum atom displacement tolerated for the neighbor lists update

References

More information about how this action can be used is available in the following articles:

• G. A. Gallet, F. Pietrucci, Structural cluster analysis of chemical reactions in solution. The Journal of Chemical Physics. 139 (2013)
• S. Pipolo, M. Salanne, G. Ferlat, S. Klotz, A. M. Saitta, F. Pietrucci, Navigating at Will on the Water Phase Diagram. Physical Review Letters. 119 (2017)