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 : # Notice how we use ROLE here in order to tell PLUMED that these are the x coordinates.
65 : # Further note that we need to use the FROM_DOMAINS flag if the MD code we are using uses
66 : # domain decomposition.
67 : xpos: PUT SHAPE=100 UNIT=length PERIODIC=NO ROLE=x FROM_DOMAINS
68 : # This is how you create a scalar to hold the timestep
69 : # The constant flag indicates that the value of the timestep doesn't change during the simulation
70 : tstep: PUT CONSTANT UNIT=time PERIODIC=NO
71 : # This is how you create a value to hold a 10 x 10 matrix in plumed whose elements are unitless
72 : matrix: PUT SHAPE=10,10 UNIT=number PERIODIC=NO
73 : # Lastly, if you want to pass a value that has a periodic domain you can do so as follows
74 : # By adding the MUTABLE flag here we pass the data to PLUMED in a way that ensures that PLUMED can modify
75 : # the value that was passed from the MD code and thus pass back a different value to the underlying MD code.
76 : tor: PUT UNIT=number PERIODIC=-pi,pi MUTABLE
77 : ```
78 :
79 : */
80 : //+ENDPLUMEDOC
81 :
82 : namespace PLMD {
83 :
84 : PLUMED_REGISTER_ACTION(ActionToPutData,"PUT")
85 :
86 7417 : void ActionToPutData::registerKeywords(Keywords& keys) {
87 7417 : ActionForInterface::registerKeywords( keys );
88 7417 : keys.add("compulsory","SHAPE","0","the shape of the value that is being passed to PLUMED");
89 7417 : 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");
90 7417 : keys.add("compulsory","FORCE_UNIT","default","the units to use for the force");
91 7417 : 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 "
92 : "is not periodic you must state this using PERIODIC=NO. Positions are passed with PERIODIC=NO even though special methods are used "
93 : "to deal with pbc");
94 7417 : keys.addFlag("CONSTANT",false,"does this quantity not depend on time");
95 7417 : keys.addFlag("FROM_DOMAINS",false,"is this quantity passed through the domain decomposition object");
96 7417 : keys.addFlag("MUTABLE",false,"can plumed change the value of the pointer that is passed from the MD code");
97 7417 : keys.remove("NUMERICAL_DERIVATIVES");
98 14834 : keys.setValueDescription("scalar/vector/matrix/grid","the data that was passed from the MD code");
99 7417 : }
100 :
101 8667 : ActionToPutData::ActionToPutData(const ActionOptions&ao):
102 : Action(ao),
103 : ActionForInterface(ao),
104 8667 : noforce(false),
105 8667 : fixed(false),
106 8667 : from_domains(false),
107 8667 : resetable(false),
108 8667 : dataCanBeSet(true),
109 8667 : unit(n),
110 8667 : mydata(DataPassingObject::create(plumed.getRealPrecision())) {
111 16049 : if( getName()!="ENERGY" && getName()!="PBC" ) {
112 : std::vector<std::size_t> shape;
113 14764 : parseVector("SHAPE",shape);
114 7382 : if( shape.size()==1 && shape[0]==0 ) {
115 1135 : shape.resize(0);
116 1135 : addValue( shape );
117 : } else {
118 6247 : addValue( shape );
119 : }
120 :
121 : std::string unitstr, funitstr;
122 7382 : parse("UNIT",unitstr);
123 7382 : parse("FORCE_UNIT",funitstr);
124 7382 : setUnit( unitstr, funitstr );
125 :
126 : // Now sort out period
127 : std::vector<std::string> period;
128 14764 : parseVector("PERIODIC",period);
129 7382 : if( period.size()==1 ) {
130 7382 : if( period[0]!="NO") {
131 0 : error("input to PERIODIC keyword does not make sense");
132 : }
133 7382 : setNotPeriodic();
134 0 : } else if( period.size()==2 ) {
135 0 : setPeriodic( period[0], period[1] );
136 : } else {
137 0 : error("input to PERIODIC keyword does not make sense");
138 : }
139 :
140 7382 : parseFlag("CONSTANT",fixed);
141 7382 : if( fixed ) {
142 3622 : noforce=true;
143 3622 : copyOutput(0)->setConstant();
144 : }
145 7382 : parseFlag("FROM_DOMAINS",from_domains);
146 7382 : parseFlag("MUTABLE",resetable);
147 7382 : }
148 8667 : }
149 :
150 8667 : void ActionToPutData::setUnit( const std::string& unitstr, const std::string& funitstr ) {
151 8667 : if( unitstr=="number" ) {
152 25 : unit=n;
153 8642 : } else if( unitstr=="energy" ) {
154 101 : unit=e;
155 8541 : } else if( unitstr=="length" ) {
156 4980 : unit=l;
157 3561 : } else if( unitstr=="mass" ) {
158 1245 : unit=m;
159 2316 : } else if( unitstr=="charge" ) {
160 1245 : unit=q;
161 1071 : } else if( unitstr=="time" ) {
162 1071 : unit=t;
163 : } else {
164 0 : error( unitstr + " is not a valid input unit");
165 : }
166 : // Set the force units
167 8667 : if( funitstr=="default" ) {
168 7422 : funit=d;
169 1245 : } else if( funitstr=="energy" ) {
170 1245 : funit=eng;
171 : } else {
172 0 : error( funitstr + " is not a valid input force unit");
173 : }
174 8667 : }
175 :
176 10006 : std::string ActionToPutData::getUnitName() const {
177 10006 : if( unit==e ) {
178 165 : return "energy";
179 : }
180 9841 : if( unit==l ) {
181 5112 : return "length";
182 : }
183 4729 : if( unit==m ) {
184 1278 : return "mass";
185 : }
186 3451 : if( unit==q ) {
187 1278 : return "charge";
188 : }
189 2173 : if( unit==t ) {
190 2173 : return "time";
191 : }
192 0 : plumed_error();
193 : }
194 :
195 486572 : void ActionToPutData::setStart( const std::string& actname, const unsigned& sss) {
196 486572 : plumed_assert( actname==getLabel() );
197 : mydata->setStart(sss);
198 486572 : }
199 :
200 486572 : void ActionToPutData::setStride( const std::string& actname, const unsigned& sss ) {
201 486572 : plumed_assert( actname==getLabel() );
202 : mydata->setStride(sss);
203 486572 : }
204 :
205 10028 : void ActionToPutData::updateUnits( DataPassingTools* passtools ) {
206 : // Don't need to do anythign if this is just a number
207 10028 : if( unit==n ) {
208 : return ;
209 : }
210 :
211 20012 : double vunits=passtools->getUnitConversion( getUnitName() );
212 : mydata->setUnit(vunits);
213 10006 : if( fixed && wasset ) {
214 2298 : mydata->share_data( 0, getPntrToValue()->getNumberOfValues(), getPntrToValue() );
215 : }
216 10006 : if( funit==eng ) {
217 1278 : mydata->setForceUnit( 1/passtools->getUnitConversion("energy"));
218 8728 : } else if( funit==d ) {
219 8728 : mydata->setForceUnit(1/passtools->getUnitConversion("energy")*vunits);
220 : }
221 : }
222 :
223 2085909 : bool ActionToPutData::setValuePointer( const std::string& actname, const TypesafePtr & val ) {
224 2085909 : if( actname!=getLabel() ) {
225 : return false;
226 : }
227 487710 : wasset=true;
228 487716 : plumed_massert( dataCanBeSet, "set " + getLabel() + " cannot be set at this time");
229 487707 : if( !from_domains ) {
230 104823 : if( !resetable && getPntrToComponent(0)->getRank()==0 ) {
231 5123 : mydata->saveValueAsDouble( val );
232 5123 : if( fixed ) {
233 1134 : mydata->share_data( 0, getPntrToValue()->getNumberOfValues(), getPntrToValue() );
234 : }
235 : } else {
236 99700 : mydata->setValuePointer(val,getPntrToComponent(0)->getShape(), !resetable);
237 : }
238 : } else {
239 765768 : mydata->setValuePointer(val,std::vector<std::size_t>(), !resetable);
240 : }
241 : return true;
242 : }
243 :
244 1054735 : bool ActionToPutData::setForcePointer( const std::string& actname, const TypesafePtr & val ) {
245 1054735 : if( actname!=getLabel() ) {
246 : return false;
247 : }
248 304899 : plumed_massert( dataCanBeSet, "force on " + getLabel() + " cannot be set at this time");
249 304899 : if( !from_domains ) {
250 70374 : mydata->setForcePointer(val,getPntrToComponent(0)->getShape());
251 : } else {
252 469050 : mydata->setForcePointer(val,std::vector<std::size_t>());
253 : }
254 : return true;
255 : }
256 :
257 1350 : void ActionToPutData::getLocalValues( std::vector<double>& vals ) const {
258 1350 : mydata->share_data( vals );
259 1350 : }
260 :
261 101798 : void ActionToPutData::wait() {
262 101798 : dataCanBeSet=false;
263 101798 : if( fixed || !wasset ) {
264 : return;
265 : }
266 : plumed_assert( wasset );
267 101798 : mydata->share_data( 0, getPntrToValue()->getNumberOfValues(), getPntrToValue() );
268 : }
269 :
270 481162 : void ActionToPutData::apply() {
271 481162 : if( getPntrToValue()->forcesWereAdded() && !noforce ) {
272 204252 : if( getName()=="ENERGY" || getDependencies().size()==0 ) {
273 45468 : mydata->add_force( getPntrToValue() );
274 : }
275 : }
276 481162 : }
277 :
278 150 : unsigned ActionToPutData::getNumberOfForcesToRescale() const {
279 150 : if( getName()!="ENERGY" || getDependencies().size()>0 ) {
280 150 : return copyOutput(0)->getNumberOfValues();
281 : }
282 0 : plumed_assert( getDependencies().size()==1 );
283 0 : plumed_assert(getDependencies()[0]); // needed for following calls, see #1046
284 0 : ActionForInterface* ai = getDependencies()[0]->castToActionForInterface();
285 0 : return ai->getNumberOfForcesToRescale();
286 : }
287 :
288 200 : void ActionToPutData::rescaleForces( const double& alpha ) {
289 200 : if( noforce ) {
290 : return;
291 : }
292 150 : wasscaled=true;
293 150 : mydata->rescale_force( getNumberOfForcesToRescale(), alpha, getPntrToValue() );
294 :
295 : }
296 :
297 798 : void ActionToPutData::writeBinary(std::ostream&o) {
298 798 : if(!fixed) {
299 456 : getPntrToValue()->writeBinary(o);
300 : }
301 798 : }
302 :
303 798 : void ActionToPutData::readBinary(std::istream&i) {
304 798 : if(!fixed) {
305 456 : getPntrToValue()->readBinary(i);
306 : }
307 798 : }
308 :
309 : }
|
