Action: SELECT_WITH_MASK

Module	valtools
Description	Usage
Use a mask to select elements of an array
output value	type
a vector/matrix of values that is obtained using a mask to select elements of interest	vector/matrix

Details and examples

Use a mask to select elements of an array

Output a scalar, vector or matrix that contains a subset of the elements in the input vector or matrix. The following example shows how we can output a scalar, v, that contains the distance between and 3 and 4 by using the mask vector m to select this element from the three element vector d:

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
mThe CONSTANT action with label m calculates the following quantities:
 Quantity   
 Type   
 Description  
m
vector
the constant value that was read from the plumed input: CONSTANTCreate a constant value that can be passed to actions This action has hidden defaults. More details VALUESthe numbers that are in your constant value=1,0,1
m: CONSTANTCreate a constant value that can be passed to actions This action uses the defaults shown here. More details VALUESthe numbers that are in your constant value=1,0,1  NROWS the number of rows in your input matrix=0 NCOLS the number of columns in your matrix=0
vThe SELECT_WITH_MASK action with label v calculates the following quantities:
 Quantity   
 Type   
 Description  
v
vector
a vector/matrix of values that is obtained using a mask to select elements of interest: SELECT_WITH_MASKUse a mask to select elements of an array More details ARGthe label for the value upon which you are going to apply the mask=d MASKan array with ones in the components that you want to discard=m

The value, m, that is passed to the keyword MASK here is a vector with the same length as d. Elements of d that whose corresponding elements in m are zero are copied to the output value v. When elements of m are non-zero the corresponding elements in d are not transferred to the output value - they are masked.

If you use this action with matrices you must use the keywords ROW_MASK and COLUMN_MASK. As shown in the example inputs below, these keywords take vectors as input. In this first example, the output matrix is $3 \times 5$ as rows of the matrix whose corresponding elements in m are non-zero are not transferred:

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 GROUPthe atoms for which you would like to calculate the adjacency matrix=1-5
d: DISTANCE_MATRIXCalculate a matrix of distances between atoms. This action uses the defaults shown here. More details GROUPthe atoms for which you would like to calculate the adjacency matrix=1-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
mThe CONSTANT action with label m calculates the following quantities:
 Quantity   
 Type   
 Description  
m
vector
the constant value that was read from the plumed input: CONSTANTCreate a constant value that can be passed to actions This action has hidden defaults. More details VALUESthe numbers that are in your constant value=0,1,1,0,0
m: CONSTANTCreate a constant value that can be passed to actions This action uses the defaults shown here. More details VALUESthe numbers that are in your constant value=0,1,1,0,0  NROWS the number of rows in your input matrix=0 NCOLS the number of columns in your matrix=0
vThe SELECT_WITH_MASK action with label v calculates the following quantities:
 Quantity   
 Type   
 Description  
v
matrix
a vector/matrix of values that is obtained using a mask to select elements of interest: SELECT_WITH_MASKUse a mask to select elements of an array More details ARGthe label for the value upon which you are going to apply the mask=d ROW_MASKan array with ones in the rows of the matrix that you want to discard=m

For this second example the output matrix is $5 \times 3$ as columns of the matrix whose corresponding elements in m are non-zero are not transferred:

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 GROUPthe atoms for which you would like to calculate the adjacency matrix=1-5
d: DISTANCE_MATRIXCalculate a matrix of distances between atoms. This action uses the defaults shown here. More details GROUPthe atoms for which you would like to calculate the adjacency matrix=1-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
mThe CONSTANT action with label m calculates the following quantities:
 Quantity   
 Type   
 Description  
m
vector
the constant value that was read from the plumed input: CONSTANTCreate a constant value that can be passed to actions This action has hidden defaults. More details VALUESthe numbers that are in your constant value=0,1,1,0,0
m: CONSTANTCreate a constant value that can be passed to actions This action uses the defaults shown here. More details VALUESthe numbers that are in your constant value=0,1,1,0,0  NROWS the number of rows in your input matrix=0 NCOLS the number of columns in your matrix=0
vThe SELECT_WITH_MASK action with label v calculates the following quantities:
 Quantity   
 Type   
 Description  
v
matrix
a vector/matrix of values that is obtained using a mask to select elements of interest: SELECT_WITH_MASKUse a mask to select elements of an array More details ARGthe label for the value upon which you are going to apply the mask=d COLUMN_MASKan array with ones in the columns of the matrix that you want to discard=m

For this final example the output matrix is $3 \times 3$ as we do not transfer the rows and the columns in d whose corresponding elements in m are non-zero.

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 GROUPthe atoms for which you would like to calculate the adjacency matrix=1-5
d: DISTANCE_MATRIXCalculate a matrix of distances between atoms. This action uses the defaults shown here. More details GROUPthe atoms for which you would like to calculate the adjacency matrix=1-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
mThe CONSTANT action with label m calculates the following quantities:
 Quantity   
 Type   
 Description  
m
vector
the constant value that was read from the plumed input: CONSTANTCreate a constant value that can be passed to actions This action has hidden defaults. More details VALUESthe numbers that are in your constant value=0,1,1,0,0
m: CONSTANTCreate a constant value that can be passed to actions This action uses the defaults shown here. More details VALUESthe numbers that are in your constant value=0,1,1,0,0  NROWS the number of rows in your input matrix=0 NCOLS the number of columns in your matrix=0
vThe SELECT_WITH_MASK action with label v calculates the following quantities:
 Quantity   
 Type   
 Description  
v
matrix
a vector/matrix of values that is obtained using a mask to select elements of interest: SELECT_WITH_MASKUse a mask to select elements of an array More details ARGthe label for the value upon which you are going to apply the mask=d ROW_MASKan array with ones in the rows of the matrix that you want to discard=m COLUMN_MASKan array with ones in the columns of the matrix that you want to discard=m

Input

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

Keyword	Type	Description
ARG	scalar/vector/matrix	the label for the value upon which you are going to apply the mask
ROW_MASK	vector	an array with ones in the rows of the matrix that you want to discard
COLUMN_MASK	vector	an array with ones in the columns of the matrix that you want to discard
MASK	vector/matrix	an array with ones in the components that you want to discard

Full list of keywords

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

Keyword	Type	Default	Description
ARG	input	none	the label for the value upon which you are going to apply the mask
ROW_MASK	input	none	an array with ones in the rows of the matrix that you want to discard
COLUMN_MASK	input	none	an array with ones in the columns of the matrix that you want to discard
MASK	input	none	an array with ones in the components that you want to discard