Action: PUT

Module	core
Description	Usage
Pass data into PLUMED
output value	type
the data that was passed from the MD code	scalar/vector/matrix/grid

Further details and examples

Pass data into PLUMED

The PUT command transfers the data from a void pointer passed to PLUMED from the calling code to a PLMD::Value. The calling object knows the shapes of the variables it is passing, so if you want to pass a 3x3 matrix from the MD code to PLUMED, you create the space to do so as follows:

plumed.cmd("readInputLine n: PUT SHAPE=3,3 UNIT=length PERIODIC=NO");

This command then creates a PLMD::Value called n that you can refer to later in your PLUMED input file. To transfer data from the void pointer called val into the PLMD::Value called n, you would then use the following command:

plumed.cmd("setValue n", val);

Notice also that if you expect PLUMED to try to apply forces on n, you can pass a void pointer called force to get the forces that PLUMED has applied on the elements of n as follows:

plumed.cmd("setValueForces n", force);

Within the PLMD::Value n, the forces that PLUMED wishes to apply on the components of the input object are stored in the std::vector called inputForce. Furthermore, whenever a PLMD::Value is created from a PUT action storedata is set to true. PUT also has a CONSTANT flag that allows you to transfer variables such as the value of the timestep that is set only once during the simulation (i.e. during startup).

Data is transferred from the input void pointers to the PLMD value when the share and wait methods are called. Vectors, e.g. positions, that are split between the domains are transferred when the share and wait methods of the DOMAIN_DECOMPOSITION action are called.

You would only use the PUT command if you were calling PLUMED from python or an MD code. The equivalent commands in a convetional PLUMED input file would look like this.

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

# This is how you create a value to hold the energy the MD code passes energy in plumed
engThe PUT action with label eng calculates the following quantities: Quantity    Type    Description  
eng scalar the data that was passed from the MD code: PUTPass data into PLUMED This action has hidden defaults. More details UNITthe unit of the quantity that is being passed to PLUMED through this value=energy PERIODICif the value being passed to plumed is periodic then you should specify the periodicity of the function=NO
eng: PUTPass data into PLUMED This action uses the defaults shown here. More details UNITthe unit of the quantity that is being passed to PLUMED through this value=energy PERIODICif the value being passed to plumed is periodic then you should specify the periodicity of the function=NO  SHAPE the shape of the value that is being passed to PLUMED=0 FORCE_UNIT the units to use for the force=default
# This is how you create an vector of the 100 x positions to plumed
xposThe PUT action with label xpos calculates the following quantities: Quantity    Type    Description  
xpos vector the data that was passed from the MD code: PUTPass data into PLUMED This action has hidden defaults. More details SHAPE the shape of the value that is being passed to PLUMED=100 UNITthe unit of the quantity that is being passed to PLUMED through this value=length PERIODICif the value being passed to plumed is periodic then you should specify the periodicity of the function=NO
xpos: PUTPass data into PLUMED This action uses the defaults shown here. More details SHAPE the shape of the value that is being passed to PLUMED=100 UNITthe unit of the quantity that is being passed to PLUMED through this value=length PERIODICif the value being passed to plumed is periodic then you should specify the periodicity of the function=NO  FORCE_UNIT the units to use for the force=default
# This is how you create a scalar to hold the timestep
# The constant flag indicates that the value of the timestep doesn't change during the simulation
tstepThe PUT action with label tstep calculates the following quantities: Quantity    Type    Description  
tstep scalar the data that was passed from the MD code: PUTPass data into PLUMED This action has hidden defaults. More details CONSTANT does this quantity not depend on time UNITthe unit of the quantity that is being passed to PLUMED through this value=time PERIODICif the value being passed to plumed is periodic then you should specify the periodicity of the function=NO
tstep: PUTPass data into PLUMED This action uses the defaults shown here. More details CONSTANT does this quantity not depend on time UNITthe unit of the quantity that is being passed to PLUMED through this value=time PERIODICif the value being passed to plumed is periodic then you should specify the periodicity of the function=NO  SHAPE the shape of the value that is being passed to PLUMED=0 FORCE_UNIT the units to use for the force=default
# This is how you create a value to hold a 10 x 10 matrix in plumed whose elements are unitless
matrixThe PUT action with label matrix calculates the following quantities: Quantity    Type    Description  
matrix matrix the data that was passed from the MD code: PUTPass data into PLUMED This action has hidden defaults. More details SHAPE the shape of the value that is being passed to PLUMED=10,10 UNITthe unit of the quantity that is being passed to PLUMED through this value=number PERIODICif the value being passed to plumed is periodic then you should specify the periodicity of the function=NO
matrix: PUTPass data into PLUMED This action uses the defaults shown here. More details SHAPE the shape of the value that is being passed to PLUMED=10,10 UNITthe unit of the quantity that is being passed to PLUMED through this value=number PERIODICif the value being passed to plumed is periodic then you should specify the periodicity of the function=NO  FORCE_UNIT the units to use for the force=default
# Lastly, if you want to pass a value that has a periodic domain you can do so as follows
torThe PUT action with label tor calculates the following quantities: Quantity    Type    Description  
tor scalar the data that was passed from the MD code: PUTPass data into PLUMED This action has hidden defaults. More details UNITthe unit of the quantity that is being passed to PLUMED through this value=number PERIODICif the value being passed to plumed is periodic then you should specify the periodicity of the function=-pi,pi
tor: PUTPass data into PLUMED This action uses the defaults shown here. More details UNITthe unit of the quantity that is being passed to PLUMED through this value=number PERIODICif the value being passed to plumed is periodic then you should specify the periodicity of the function=-pi,pi  SHAPE the shape of the value that is being passed to PLUMED=0 FORCE_UNIT the units to use for the force=default

Syntax

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

Keyword	Type	Default	Description
SHAPE	compulsory	0	the shape of the value that is being passed to PLUMED
UNIT	compulsory	none	the unit of the quantity that is being passed to PLUMED through this value
FORCE_UNIT	compulsory	default	the units to use for the force
PERIODIC	compulsory	none	if the value being passed to plumed is periodic then you should specify the periodicity of the function
NUMERICAL_DERIVATIVES	optional	false	calculate the derivatives for these quantities numerically
ROLE	optional	not used	Get the role this value plays in the code can be x/y/z/m/q to signify that this is x, y, z positions of atoms or masses or charges of atoms
CONSTANT	optional	false	does this quantity not depend on time
FROM_DOMAINS	optional	false	is this quantity passed through the domain decomposition object
MUTABLE	optional	false	can plumed change the value of the pointer that is passed from the MD code

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search

Quantity	Type	Description
eng	scalar	the data that was passed from the MD code