Line data Source code
1 : /* +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
2 : Copyright (c) 2017-2023 The plumed team
3 : (see the PEOPLE file at the root of the distribution for a list of names)
4 :
5 : See http://www.plumed.org for more information.
6 :
7 : This file is part of plumed, version 2.
8 :
9 : plumed is free software: you can redistribute it and/or modify
10 : it under the terms of the GNU Lesser General Public License as published by
11 : the Free Software Foundation, either version 3 of the License, or
12 : (at your option) any later version.
13 :
14 : plumed is distributed in the hope that it will be useful,
15 : but WITHOUT ANY WARRANTY; without even the implied warranty of
16 : MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 : GNU Lesser General Public License for more details.
18 :
19 : You should have received a copy of the GNU Lesser General Public License
20 : along with plumed. If not, see <http://www.gnu.org/licenses/>.
21 : +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ */
22 : #include "ActionToPutData.h"
23 : #include "ActionRegister.h"
24 : #include "PlumedMain.h"
25 : #include "ActionSet.h"
26 :
27 : //+PLUMEDOC ANALYSIS PUT
28 : /*
29 : Pass data into PLUMED
30 :
31 : The PUT command transfers the data from a void pointer passed to PLUMED from the calling code to a PLMD::Value. The calling
32 : 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:
33 :
34 : ```c++
35 : plumed.cmd("readInputLine n: PUT SHAPE=3,3 UNIT=length PERIODIC=NO");
36 : ```
37 :
38 : 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
39 : called `n`, you would then use the following command:
40 :
41 : ```c++
42 : plumed.cmd("setValue n", val);
43 : ```
44 :
45 : 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:
46 :
47 : ```c++
48 : plumed.cmd("setValueForces n", force);
49 : ```
50 :
51 : 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
52 : 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
53 : simulation (i.e. during startup).
54 :
55 : 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
56 : are transferred when the share and wait methods of the [DOMAIN_DECOMPOSITION](DOMAIN_DECOMPOSITION.md) action are called.
57 :
58 : 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.
59 :
60 : ```plumed
61 : # This is how you create a value to hold the energy the MD code passes energy in plumed
62 : eng: PUT UNIT=energy PERIODIC=NO
63 : # This is how you create an vector of the 100 x positions to plumed
64 : xpos: PUT SHAPE=100 UNIT=length PERIODIC=NO
65 : # This is how you create a scalar to hold the timestep
66 : # The constant flag indicates that the value of the timestep doesn't change during the simulation
67 : tstep: PUT CONSTANT UNIT=time PERIODIC=NO
68 : # This is how you create a value to hold a 10 x 10 matrix in plumed whose elements are unitless
69 : matrix: PUT SHAPE=10,10 UNIT=number PERIODIC=NO
70 : # Lastly, if you want to pass a value that has a periodic domain you can do so as follows
71 : tor: PUT UNIT=number PERIODIC=-pi,pi
72 : ```
73 :
74 : */
75 : //+ENDPLUMEDOC
76 :
77 : namespace PLMD {
78 :
79 : PLUMED_REGISTER_ACTION(ActionToPutData,"PUT")
80 :
81 7244 : void ActionToPutData::registerKeywords(Keywords& keys) {
82 7244 : ActionForInterface::registerKeywords( keys );
83 7244 : keys.add("compulsory","SHAPE","0","the shape of the value that is being passed to PLUMED");
84 7244 : keys.add("compulsory","UNIT","the unit of the quantity that is being passed to PLUMED through this value. Can be either number, energy, time, length, mass or charge");
85 7244 : keys.add("compulsory","FORCE_UNIT","default","the units to use for the force");
86 7244 : keys.add("compulsory","PERIODIC","if the value being passed to plumed is periodic then you should specify the periodicity of the function. If the value "
87 : "is not periodic you must state this using PERIODIC=NO. Positions are passed with PERIODIC=NO even though special methods are used "
88 : "to deal with pbc");
89 7244 : keys.addFlag("CONSTANT",false,"does this quantity not depend on time");
90 7244 : keys.addFlag("FROM_DOMAINS",false,"is this quantity passed through the domain decomposition object");
91 7244 : keys.addFlag("MUTABLE",false,"can plumed change the value of the pointer that is passed from the MD code");
92 14488 : keys.setValueDescription("scalar/vector/matrix/grid","the data that was passed from the MD code");
93 7244 : }
94 :
95 8465 : ActionToPutData::ActionToPutData(const ActionOptions&ao):
96 : Action(ao),
97 : ActionForInterface(ao),
98 8465 : noforce(false),
99 8465 : fixed(false),
100 8465 : from_domains(false),
101 8465 : resetable(false),
102 8465 : dataCanBeSet(true),
103 8465 : unit(n),
104 8465 : mydata(DataPassingObject::create(plumed.getRealPrecision())) {
105 15674 : if( getName()!="ENERGY" && getName()!="PBC" ) {
106 : std::vector<unsigned> shape;
107 14418 : parseVector("SHAPE",shape);
108 7209 : if( shape.size()==1 && shape[0]==0 ) {
109 1109 : shape.resize(0);
110 1109 : addValue( shape );
111 : } else {
112 6100 : addValue( shape );
113 : }
114 :
115 : std::string unitstr, funitstr;
116 7209 : parse("UNIT",unitstr);
117 7209 : parse("FORCE_UNIT",funitstr);
118 7209 : setUnit( unitstr, funitstr );
119 :
120 : // Now sort out period
121 : std::vector<std::string> period;
122 14418 : parseVector("PERIODIC",period);
123 7209 : if( period.size()==1 ) {
124 7207 : if( period[0]!="NO") {
125 0 : error("input to PERIODIC keyword does not make sense");
126 : }
127 7207 : setNotPeriodic();
128 2 : } else if( period.size()==2 ) {
129 2 : setPeriodic( period[0], period[1] );
130 : } else {
131 0 : error("input to PERIODIC keyword does not make sense");
132 : }
133 :
134 7209 : parseFlag("CONSTANT",fixed);
135 7209 : if( fixed ) {
136 3538 : noforce=true;
137 3538 : copyOutput(0)->setConstant();
138 : }
139 7209 : parseFlag("FROM_DOMAINS",from_domains);
140 7209 : parseFlag("MUTABLE",resetable);
141 7209 : }
142 8465 : }
143 :
144 8465 : void ActionToPutData::setUnit( const std::string& unitstr, const std::string& funitstr ) {
145 8465 : if( unitstr=="number" ) {
146 23 : unit=n;
147 8442 : } else if( unitstr=="energy" ) {
148 101 : unit=e;
149 8341 : } else if( unitstr=="length" ) {
150 4864 : unit=l;
151 3477 : } else if( unitstr=="mass" ) {
152 1216 : unit=m;
153 2261 : } else if( unitstr=="charge" ) {
154 1216 : unit=q;
155 1045 : } else if( unitstr=="time" ) {
156 1045 : unit=t;
157 : } else {
158 0 : error( unitstr + " is not a valid input unit");
159 : }
160 : // Set the force units
161 8465 : if( funitstr=="default" ) {
162 7249 : funit=d;
163 1216 : } else if( funitstr=="energy" ) {
164 1216 : funit=eng;
165 : } else {
166 0 : error( funitstr + " is not a valid input force unit");
167 : }
168 8465 : }
169 :
170 9780 : std::string ActionToPutData::getUnitName() const {
171 9780 : if( unit==e ) {
172 165 : return "energy";
173 : }
174 9615 : if( unit==l ) {
175 4996 : return "length";
176 : }
177 4619 : if( unit==m ) {
178 1249 : return "mass";
179 : }
180 3370 : if( unit==q ) {
181 1249 : return "charge";
182 : }
183 2121 : if( unit==t ) {
184 2121 : return "time";
185 : }
186 0 : plumed_error();
187 : }
188 :
189 463738 : void ActionToPutData::setStart( const std::string& name, const unsigned& sss) {
190 463738 : plumed_assert( name==getLabel() );
191 : mydata->setStart(sss);
192 463738 : }
193 :
194 463738 : void ActionToPutData::setStride( const std::string& name, const unsigned& sss ) {
195 463738 : plumed_assert( name==getLabel() );
196 : mydata->setStride(sss);
197 463738 : }
198 :
199 9800 : void ActionToPutData::updateUnits( DataPassingTools* passtools ) {
200 : // Don't need to do anythign if this is just a number
201 9800 : if( unit==n ) {
202 : return ;
203 : }
204 :
205 19560 : double vunits=passtools->getUnitConversion( getUnitName() );
206 : mydata->setUnit(vunits);
207 9780 : if( fixed && wasset ) {
208 2246 : mydata->share_data( 0, getPntrToValue()->getNumberOfValues(), getPntrToValue() );
209 : }
210 9780 : if( funit==eng ) {
211 1249 : mydata->setForceUnit( 1/passtools->getUnitConversion("energy"));
212 8531 : } else if( funit==d ) {
213 8531 : mydata->setForceUnit(1/passtools->getUnitConversion("energy")*vunits);
214 : }
215 : }
216 :
217 1989697 : bool ActionToPutData::setValuePointer( const std::string& name, const TypesafePtr & val ) {
218 1989697 : if( name!=getLabel() ) {
219 : return false;
220 : }
221 464850 : wasset=true;
222 464856 : plumed_massert( dataCanBeSet, "set " + getLabel() + " cannot be set at this time");
223 464847 : if( !from_domains ) {
224 99171 : if( !resetable && getPntrToComponent(0)->getRank()==0 ) {
225 5097 : mydata->saveValueAsDouble( val );
226 5097 : if( fixed ) {
227 1108 : mydata->share_data( 0, getPntrToValue()->getNumberOfValues(), getPntrToValue() );
228 : }
229 : } else {
230 94074 : mydata->setValuePointer(val,getPntrToComponent(0)->getShape(), !resetable);
231 : }
232 : } else {
233 731352 : mydata->setValuePointer(val,std::vector<unsigned>(), !resetable);
234 : }
235 : return true;
236 : }
237 :
238 1006555 : bool ActionToPutData::setForcePointer( const std::string& name, const TypesafePtr & val ) {
239 1006555 : if( name!=getLabel() ) {
240 : return false;
241 : }
242 291131 : plumed_massert( dataCanBeSet, "force on " + getLabel() + " cannot be set at this time");
243 291131 : if( !from_domains ) {
244 66932 : mydata->setForcePointer(val,getPntrToComponent(0)->getShape());
245 : } else {
246 448398 : mydata->setForcePointer(val,std::vector<unsigned>());
247 : }
248 : return true;
249 : }
250 :
251 1350 : void ActionToPutData::getLocalValues( std::vector<double>& vals ) const {
252 1350 : mydata->share_data( vals );
253 1350 : }
254 :
255 96113 : void ActionToPutData::wait() {
256 96113 : dataCanBeSet=false;
257 96113 : if( fixed || !wasset ) {
258 : return;
259 : }
260 : plumed_assert( wasset );
261 96113 : mydata->share_data( 0, getPntrToValue()->getNumberOfValues(), getPntrToValue() );
262 : }
263 :
264 457972 : void ActionToPutData::apply() {
265 457972 : if( getPntrToValue()->forcesWereAdded() && !noforce ) {
266 190352 : if( getName()=="ENERGY" || getDependencies().size()==0 ) {
267 41993 : mydata->add_force( getPntrToValue() );
268 : }
269 : }
270 457972 : }
271 :
272 150 : unsigned ActionToPutData::getNumberOfForcesToRescale() const {
273 150 : if( getName()!="ENERGY" || getDependencies().size()>0 ) {
274 150 : return copyOutput(0)->getNumberOfValues();
275 : }
276 0 : plumed_assert( getDependencies().size()==1 );
277 0 : plumed_assert(getDependencies()[0]); // needed for following calls, see #1046
278 0 : ActionForInterface* ai = getDependencies()[0]->castToActionForInterface();
279 0 : return ai->getNumberOfForcesToRescale();
280 : }
281 :
282 200 : void ActionToPutData::rescaleForces( const double& alpha ) {
283 200 : if( noforce ) {
284 : return;
285 : }
286 150 : wasscaled=true;
287 150 : mydata->rescale_force( getNumberOfForcesToRescale(), alpha, getPntrToValue() );
288 :
289 : }
290 :
291 798 : void ActionToPutData::writeBinary(std::ostream&o) {
292 798 : if(!fixed) {
293 456 : getPntrToValue()->writeBinary(o);
294 : }
295 798 : }
296 :
297 798 : void ActionToPutData::readBinary(std::istream&i) {
298 798 : if(!fixed) {
299 456 : getPntrToValue()->readBinary(i);
300 : }
301 798 : }
302 :
303 : }
|
