Action: COLLECT

Module	generic
Description	Usage
Collect data from the trajectory for later analysis
output value	type
the time series for the input quantity	vector/matrix

Input

The arguments that serve as the input for this action are specified using one or more of the keywords in the following table.

Further details and examples

Collect data from the trajectory for later analysis

The way this command can be used is illustrated by the following example:

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

dThe DISTANCE action with label d calculates the following quantities:
 Quantity   
 Type   
 Description  
d
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
cThe COLLECT action with label c calculates the following quantities:
 Quantity   
 Type   
 Description  
c
vector
the time series for the input quantity: COLLECTCollect data from the trajectory for later analysis This action has hidden defaults. More details ARGthe label of the value whose time series is being stored for later analysis=d STRIDE the frequency with which the data should be collected and added to the quantity being averaged=1
c: COLLECTCollect data from the trajectory for later analysis This action uses the defaults shown here. More details ARGthe label of the value whose time series is being stored for later analysis=d STRIDE the frequency with which the data should be collected and added to the quantity being averaged=1  TYPE required if you are collecting an object with rank>0=auto CLEAR the frequency with which to clear all the accumulated data=0
DUMPVECTORPrint a vector to a file More details ARGthe labels of vectors/matrices that should be output in the file=c FILE the file on which to write the vetors=timeseries

The COLLECT command in the input above stores the time series of distances over the whole trajectory. The STRIDE keyword controls how frequently data is stored and the DUMPVECTOR command then outputs the full time series of d values at the end of the calculation.

The above example is not particularly useful as you can achieve the same result by using simply a DISTANCE command and the PRINT command. The COLLECT command is useful if you want use the whole trajectory to perform a analysis such as dimensionality reduction (see dimred). The shortcut command COLLECT_FRAMES uses this action heavily and allows one to easily deal with the fact that COLLECT can only collect the time series for one PLUMED Value at a time.

Collecting a part of the trajectory

You can use the CLEAR keyword to collect a subset of the trajectory as illustrated below:

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

dThe DISTANCE action with label d calculates the following quantities:
 Quantity   
 Type   
 Description  
d
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
cThe COLLECT action with label c calculates the following quantities:
 Quantity   
 Type   
 Description  
c
vector
the time series for the input quantity: COLLECTCollect data from the trajectory for later analysis This action has hidden defaults. More details ARGthe label of the value whose time series is being stored for later analysis=d STRIDE the frequency with which the data should be collected and added to the quantity being averaged=1 CLEAR the frequency with which to clear all the accumulated data=1000
c: COLLECTCollect data from the trajectory for later analysis This action uses the defaults shown here. More details ARGthe label of the value whose time series is being stored for later analysis=d STRIDE the frequency with which the data should be collected and added to the quantity being averaged=1 CLEAR the frequency with which to clear all the accumulated data=1000  TYPE required if you are collecting an object with rank>0=auto
DUMPVECTORPrint a vector to a file More details ARGthe labels of vectors/matrices that should be output in the file=c FILE the file on which to write the vetors=timeseries STRIDE the frequency with which the grid should be output to the file=1000

This outputs files contain from this input contain 1000-frame blocks of the trajectory for the distance between atom 1 and 2. This type of input might proove useful if you wish to perform separate analysis on different parts of the trajectory for later comparison.

Collecting vectors

You can use the collect command even if the input value has a rank that is greater than zero. For example, the following input collects vectors of distances from the trajectory:

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

dThe DISTANCE action with label d calculates the following quantities:
 Quantity   
 Type   
 Description  
d
vector
the DISTANCE for each set of specified atoms: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMS1the pair of atom that we are calculating the distance between=1,2 ATOMS2the pair of atom that we are calculating the distance between=3,4 ATOMS3the pair of atom that we are calculating the distance between=5,6 ATOMS4the pair of atom that we are calculating the distance between=7,8
cThe COLLECT action with label c calculates the following quantities:
 Quantity   
 Type   
 Description  
c
vector
the time series for the input quantity: COLLECTCollect data from the trajectory for later analysis More details ARGthe label of the value whose time series is being stored for later analysis=d TYPE required if you are collecting an object with rank>0=vector STRIDE the frequency with which the data should be collected and added to the quantity being averaged=1 CLEAR the frequency with which to clear all the accumulated data=100
DUMPVECTORPrint a vector to a file More details ARGthe labels of vectors/matrices that should be output in the file=c FILE the file on which to write the vetors=timeseries STRIDE the frequency with which the grid should be output to the file=100

Notice that if the input to the collect action is a value with rank>0 you must use the TYPE keyword to specify whether the output Value is a vector or matrix. In the above input we are storing a vector so the DUMPVECTOR command outputs a list of 400 distances - 4 distances for each frame. The assumption in the input above is that the four distances that have been computed by the DISTANCES command are indistinguishable.

By using the following input we can ensure the the four distances are treated as distinguishable when we do any analysis:

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

dThe DISTANCE action with label d calculates the following quantities:
 Quantity   
 Type   
 Description  
d
vector
the DISTANCE for each set of specified atoms: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMS1the pair of atom that we are calculating the distance between=1,2 ATOMS2the pair of atom that we are calculating the distance between=3,4 ATOMS3the pair of atom that we are calculating the distance between=5,6 ATOMS4the pair of atom that we are calculating the distance between=7,8
cThe COLLECT action with label c calculates the following quantities:
 Quantity   
 Type   
 Description  
c
matrix
the time series for the input quantity: COLLECTCollect data from the trajectory for later analysis More details ARGthe label of the value whose time series is being stored for later analysis=d TYPE required if you are collecting an object with rank>0=matrix STRIDE the frequency with which the data should be collected and added to the quantity being averaged=1 CLEAR the frequency with which to clear all the accumulated data=100
DUMPVECTORPrint a vector to a file More details ARGthe labels of vectors/matrices that should be output in the file=c FILE the file on which to write the vetors=timeseries STRIDE the frequency with which the grid should be output to the file=100

The value c is now a $100\times 4$ matrix. Furthermore, when we use DUMPVECTOR to output the output file will contain four columns of data.

Collecting matrices

You can also use this action to collect a matrix as illustrated by the following example:

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

dThe DISTANCE_MATRIX action with label d calculates the following quantities:
 Quantity   
 Type   
 Description  
d
matrix
a matrix containing the weights for the bonds between each pair of atoms: DISTANCE_MATRIXCalculate a matrix of distances between atoms. This action has hidden defaults. More details GROUPAwhen you are calculating the adjacency matrix between two sets of atoms this keyword is used to specify the atoms along with the keyword GROUPB=1,2 GROUPBwhen you are calculating the adjacency matrix between two sets of atoms this keyword is used to specify the atoms along with the keyword GROUPA=3,4,5
d: DISTANCE_MATRIXCalculate a matrix of distances between atoms. This action uses the defaults shown here. More details GROUPAwhen you are calculating the adjacency matrix between two sets of atoms this keyword is used to specify the atoms along with the keyword GROUPB=1,2 GROUPBwhen you are calculating the adjacency matrix between two sets of atoms this keyword is used to specify the atoms along with the keyword GROUPA=3,4,5  NL_CUTOFF The cutoff for the neighbor list=0.0 NL_STRIDE The frequency with which we are updating the atoms in the neighbor list=1 CUTOFF ignore distances that have a value larger than this cutoff=-1
cThe COLLECT action with label c calculates the following quantities:
 Quantity   
 Type   
 Description  
c
vector
the time series for the input quantity: COLLECTCollect data from the trajectory for later analysis More details ARGthe label of the value whose time series is being stored for later analysis=d TYPE required if you are collecting an object with rank>0=vector STRIDE the frequency with which the data should be collected and added to the quantity being averaged=1 CLEAR the frequency with which to clear all the accumulated data=100
DUMPVECTORPrint a vector to a file More details ARGthe labels of vectors/matrices that should be output in the file=c FILE the file on which to write the vetors=timeseries STRIDE the frequency with which the grid should be output to the file=100

The value c here is a vector with 600 elements as the input matrix is converted to a vector. These vectors are then stored in one contiguous object.

If by contrast we use TYPE=matrix as shown below:

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

dThe DISTANCE_MATRIX action with label d calculates the following quantities:
 Quantity   
 Type   
 Description  
d
matrix
a matrix containing the weights for the bonds between each pair of atoms: DISTANCE_MATRIXCalculate a matrix of distances between atoms. This action has hidden defaults. More details GROUPAwhen you are calculating the adjacency matrix between two sets of atoms this keyword is used to specify the atoms along with the keyword GROUPB=1,2 GROUPBwhen you are calculating the adjacency matrix between two sets of atoms this keyword is used to specify the atoms along with the keyword GROUPA=3,4,5
d: DISTANCE_MATRIXCalculate a matrix of distances between atoms. This action uses the defaults shown here. More details GROUPAwhen you are calculating the adjacency matrix between two sets of atoms this keyword is used to specify the atoms along with the keyword GROUPB=1,2 GROUPBwhen you are calculating the adjacency matrix between two sets of atoms this keyword is used to specify the atoms along with the keyword GROUPA=3,4,5  NL_CUTOFF The cutoff for the neighbor list=0.0 NL_STRIDE The frequency with which we are updating the atoms in the neighbor list=1 CUTOFF ignore distances that have a value larger than this cutoff=-1
cThe COLLECT action with label c calculates the following quantities:
 Quantity   
 Type   
 Description  
c
matrix
the time series for the input quantity: COLLECTCollect data from the trajectory for later analysis More details ARGthe label of the value whose time series is being stored for later analysis=d TYPE required if you are collecting an object with rank>0=matrix STRIDE the frequency with which the data should be collected and added to the quantity being averaged=1 CLEAR the frequency with which to clear all the accumulated data=100
DUMPVECTORPrint a vector to a file More details ARGthe labels of vectors/matrices that should be output in the file=c FILE the file on which to write the vetors=timeseries STRIDE the frequency with which the grid should be output to the file=100

A $100 \times 6$ matrix is stored. Each row of this matrix contains a vectorized version of the input matrix. There is currently no way to store the collected data in a way that recognises that each of the input PLUMED Value was a matrix. You also cannot use this action to store functions evaluated on a grid.

Syntax

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