Regular Expressions

When you use need to pass many arguments to a PLUMED action, being them components of a few collective variables or also multiple collective variables, you might find it convenient to use regular expressions.

Since version 2.1, plumed takes advantage of a configuration scripts that detects libraries installed on your system. If regex library is found, then you will be able to use regular expressions to refer to collective variables or function names.

Regular expressions are enclosed in round braces and must not contain spaces (the components names have no spaces indeed, so why use them?).

As an example the command:

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

d1: DISTANCE 
ATOMS
the pair of atom that we are calculating the distance between. 
=1,2 
COMPONENTS
( default=off ) calculate the x, y and z components of the distance separately and
store them as label.x, 
 The DISTANCE action with label d1 calculates the following quantities:

 Quantity   
 Description  
d1.x
the x-component of the vector connecting the two atoms
d1.y
the y-component of the vector connecting the two atoms
d1.z
the z-component of the vector connecting the two atoms


PRINT 
ARG
the input for this action is the scalar output from one or more other actions. 
=(d1\.[xy]) 
STRIDE
compulsory keyword ( default=1 )
the frequency with which the quantities of interest should be output 
=100 
FILE
the name of the file on which to output these quantities 
=colvar 
FMT
the format that should be used to output real numbers 
=%8.4f The PRINT action with label 

will cause both the d1.x and d1.y components of the DISTANCE action to be printed.

Notice that selection does not happen in alphabetic order, nor in the order in which [xy] are listed, but rather in the order in which the two variables have been created by PLUMED. Also notice that the . character must be escaped as \. in order to interpret it as a literal .. An un-escaped dot is a wildcard which is matched by any character, So as an example

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

d1: DISTANCE 
ATOMS
the pair of atom that we are calculating the distance between. 
=1,2 
COMPONENTS
( default=off ) calculate the x, y and z components of the distance separately and
store them as label.x, 
 The DISTANCE action with label d1 calculates the following quantities:

 Quantity   
 Description  
d1.x
the x-component of the vector connecting the two atoms
d1.y
the y-component of the vector connecting the two atoms
d1.z
the z-component of the vector connecting the two atoms


dxy: DISTANCE 
ATOMS
the pair of atom that we are calculating the distance between. 
=1,3 The DISTANCE action with label dxy calculates a single scalar value
# this will match d1.x,d1.y,dxy
PRINT 
ARG
the input for this action is the scalar output from one or more other actions. 
=(d1.[xy]) 
STRIDE
compulsory keyword ( default=1 )
the frequency with which the quantities of interest should be output 
=100 
FILE
the name of the file on which to output these quantities 
=colvar 
FMT
the format that should be used to output real numbers 
=%8.4f The PRINT action with label 
# while this will match d1.x,d1.y only
PRINT 
ARG
the input for this action is the scalar output from one or more other actions. 
=(d1\.[xy]) 
STRIDE
compulsory keyword ( default=1 )
the frequency with which the quantities of interest should be output 
=100 
FILE
the name of the file on which to output these quantities 
=colvar 
FMT
the format that should be used to output real numbers 
=%8.4f The PRINT action with label 

You can concatenate more than one regular expression by using comma separated regular expressions. The resulting matches will be concatenated:

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

t1: TORSION 
ATOMS
the four atoms involved in the torsional angle 
=5,7,9,15 The TORSION action with label t1 calculates a single scalar value
t2: TORSION 
ATOMS
the four atoms involved in the torsional angle 
=7,9,15,17 The TORSION action with label t2 calculates a single scalar value
d1: DISTANCE 
ATOMS
the pair of atom that we are calculating the distance between. 
=7,17 
COMPONENTS
( default=off ) calculate the x, y and z components of the distance separately and
store them as label.x, 
 The DISTANCE action with label d1 calculates the following quantities:

 Quantity   
 Description  
d1.x
the x-component of the vector connecting the two atoms
d1.y
the y-component of the vector connecting the two atoms
d1.z
the z-component of the vector connecting the two atoms


# The first expression matches d1.x and d1.y
# The second expression matches t1 and t2
PRINT 
ARG
the input for this action is the scalar output from one or more other actions. 
=(d1\.[xy]),(t[0-9]) 
STRIDE
compulsory keyword ( default=1 )
the frequency with which the quantities of interest should be output 
=100 
FILE
the name of the file on which to output these quantities 
=colvar 
FMT
the format that should be used to output real numbers 
=%8.4f The PRINT action with label 
# Thus this is the same as ARG=d1.x,d1.y,t1,t2

Be aware that if you have overlapping selections they will be duplicated. As an alternative you could use the "or" operator |:

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

t1: TORSION 
ATOMS
the four atoms involved in the torsional angle 
=5,7,9,15 The TORSION action with label t1 calculates a single scalar value
t2: TORSION 
ATOMS
the four atoms involved in the torsional angle 
=7,9,15,17 The TORSION action with label t2 calculates a single scalar value
d1: DISTANCE 
ATOMS
the pair of atom that we are calculating the distance between. 
=7,17 
COMPONENTS
( default=off ) calculate the x, y and z components of the distance separately and
store them as label.x, 
 The DISTANCE action with label d1 calculates the following quantities:

 Quantity   
 Description  
d1.x
the x-component of the vector connecting the two atoms
d1.y
the y-component of the vector connecting the two atoms
d1.z
the z-component of the vector connecting the two atoms


# Here is a single regular expression
PRINT 
ARG
the input for this action is the scalar output from one or more other actions. 
=(d1\.[xy]|t[0-9]) 
STRIDE
compulsory keyword ( default=1 )
the frequency with which the quantities of interest should be output 
=100 
FILE
the name of the file on which to output these quantities 
=colvar 
FMT
the format that should be used to output real numbers 
=%8.4f The PRINT action with label 
# Thus this is the same as ARG=t1,t2,d1.x,d1.y

this selects the same set of arguments as the previous example.

Note

Be careful you do not confuse regular expressions, which are triggered by the parenthesis () and only available when PLUMED has been compiled with the regex library, with the capability of PLUMED to use * as a wildcard in arguments:

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

d1: DISTANCE 
ATOMS
the pair of atom that we are calculating the distance between. 
=1,2 
COMPONENTS
( default=off ) calculate the x, y and z components of the distance separately and
store them as label.x, 
 The DISTANCE action with label d1 calculates the following quantities:

 Quantity   
 Description  
d1.x
the x-component of the vector connecting the two atoms
d1.y
the y-component of the vector connecting the two atoms
d1.z
the z-component of the vector connecting the two atoms


# this is a regular expression that selects all components of d1
# i.e. d1.x d1.y and d1.z
PRINT 
ARG
the input for this action is the scalar output from one or more other actions. 
=(d1\..*) 
STRIDE
compulsory keyword ( default=1 )
the frequency with which the quantities of interest should be output 
=100 
FILE
the name of the file on which to output these quantities 
=colvar_reg 
FMT
the format that should be used to output real numbers 
=%8.4f The PRINT action with label 
# this is a wildcard that selects all the components of d1 as well
PRINT 
ARG
the input for this action is the scalar output from one or more other actions. 
=d1.* 
STRIDE
compulsory keyword ( default=1 )
the frequency with which the quantities of interest should be output 
=100 
FILE
the name of the file on which to output these quantities 
=colvar_wild 
FMT
the format that should be used to output real numbers 
=%8.4f The PRINT action with label 

Regular expressions are way more flexible than wildcards!

You can check the log to see whether or not your regular expression is picking the set of components you desire.

For more information on regular expressions visit http://www.regular-expressions.info/reference.html.