Line data Source code
1 : /* +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
2 : Copyright (c) 2011-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 "core/ActionSetup.h"
23 : #include "core/ActionRegister.h"
24 : #include "core/PlumedMain.h"
25 : #include "tools/Exception.h"
26 :
27 : namespace PLMD {
28 : namespace setup {
29 :
30 : //+PLUMEDOC GENERIC UNITS
31 : /*
32 : This command sets the internal units for the code.
33 :
34 : The default units in the plumed input and output files are discussed [here](parsing.md). If you would like
35 : to use units that are different from these defaults you can use the UNITS command. This directive MUST
36 : appear at the BEGINNING of the plumed.dat file and same units must be used throughout the plumed.dat file.
37 :
38 : The following input demonstrates one way that you can use the UNITS command to change the units.
39 :
40 : ```plumed
41 : # this is using Angstrom - kj/mol - fs
42 : UNITS LENGTH=A TIME=fs ENERGY=kj/mol MASS=amu CHARGE=e
43 :
44 : # compute distance between atoms 1 and 4
45 : d: DISTANCE ATOMS=1,4
46 :
47 : # print time and distance on a COLVAR file
48 : # times and distances in this file will be in fs and A respectively
49 : PRINT ARG=d FILE=COLVAR
50 :
51 : # dump atoms 1 to 100 on a 'out.gro' file
52 : # The positions in the gro file here will be written
53 : # in nm because this is the convention for gro files.
54 : DUMPATOMS FILE=out.gro STRIDE=10 ATOMS=1-100
55 :
56 : # dump atoms 1 to 100 on a 'out.xyz' file
57 : # The position in the xyz file here will be written
58 : # in A as there is no conventional units for xyz files
59 : # and the plumed length units has been set to Angstroms.
60 : DUMPATOMS FILE=out.xyz STRIDE=10 ATOMS=1-100
61 : ```
62 :
63 : In the example input above strings are used to set the units. The following table details all the strings
64 : that can be used when setting units. Note that the strings are case sensitive.
65 :
66 : | Quantity | Default | Alternatives |
67 : |:---------|:--------|:-------------|
68 : | Length | nm | A (for Angstrom), um (for micrometer), Bohr (0.052917721067 nm) |
69 : | Energy | kj/mol | j/mol, kcal/mol (4.184 kj/mol), eV (96.48530749925792 kj/mol), Ha (for Hartree, 2625.499638 kj/mol) |
70 : | Time | ps | fs, ns, atomic (2.418884326509e-5 ps) |
71 : | Mass | amu | |
72 : | Charge | e | |
73 :
74 : If you want to use a unit that is not specified in the table above you can specify a factor for converting the default unit to
75 : your chosen unit. As an example of how this works in practice the example below converts lengths and times into A and fs by
76 : giving explicit values for the conversion factors.
77 :
78 : ```plumed
79 : UNITS LENGTH=0.1 TIME=0.001
80 : ```
81 :
82 : The input above tells PLUMED that lengths in nm should be divided by 0.1 so as to convert them to Anstroms. Times in ps
83 : should be divded by 0.001 to convert them from ps to fs. Eneriges, masses and charges will be in the default units of
84 : kJ/mol, amu and e as we have not specified conversion parameters or specific units for these quantities.
85 :
86 : To reitterate, the default or the units specified in the UNITS command are used in all input and output
87 : files. The only exceptions are file formats for which there is a specific convention concerning
88 : the units. For example, trajectories written in .gro format (with [DUMPATOMS](DUMPATOMS.md)) will
89 : always in nm.
90 :
91 : ## Working with Lennard Jones
92 :
93 : If you are using [simplemd](simplemd.md) to perform simulations using the Lennard Jones potential in
94 : [reduced units](https://en.wikipedia.org/wiki/Lennard-Jones_potential) you can tell PLUMED to use reduced units using the
95 : `NATURAL` flag as shown below:
96 :
97 : ```plumed
98 : UNITS NATURAL
99 : ```
100 :
101 : */
102 : //+ENDPLUMEDOC
103 :
104 : class Units :
105 : public virtual ActionSetup {
106 : public:
107 : static void registerKeywords( Keywords& keys );
108 : explicit Units(const ActionOptions&ao);
109 : };
110 :
111 : PLUMED_REGISTER_ACTION(Units,"UNITS")
112 :
113 45 : void Units::registerKeywords( Keywords& keys ) {
114 45 : ActionSetup::registerKeywords(keys);
115 45 : keys.add("optional","LENGTH","the units of lengths. Either specify a conversion factor from the default, nm, or use one of the defined units, A (for angstroms), um (for micrometer), and Bohr.");
116 45 : keys.add("optional","ENERGY","the units of energy. Either specify a conversion factor from the default, kj/mol, or use one of the defined units, j/mol, kcal/mol and Ha (for Hartree)");
117 45 : keys.add("optional","TIME","the units of time. Either specify a conversion factor from the default, ps, or use one of the defined units, ns, fs, and atomic");
118 45 : keys.add("optional","MASS","the units of masses. Specify a conversion factor from the default, amu");
119 45 : keys.add("optional","CHARGE","the units of charges. Specify a conversion factor from the default, e");
120 45 : keys.addFlag("NATURAL",false,"use natural units");
121 45 : }
122 :
123 41 : Units::Units(const ActionOptions&ao):
124 : Action(ao),
125 41 : ActionSetup(ao) {
126 41 : PLMD::Units u;
127 :
128 : std::string s;
129 :
130 : s="";
131 82 : parse("LENGTH",s);
132 41 : if(s.length()>0) {
133 32 : u.setLength(s);
134 : }
135 41 : if(u.getLengthString().length()>0 && u.getLengthString()=="nm") {
136 9 : log.printf(" length: %s\n",u.getLengthString().c_str());
137 32 : } else if(u.getLengthString().length()>0 && u.getLengthString()!="nm") {
138 30 : log.printf(" length: %s = %g nm\n",u.getLengthString().c_str(),u.getLength());
139 : } else {
140 2 : log.printf(" length: %g nm\n",u.getLength());
141 : }
142 :
143 : s="";
144 82 : parse("ENERGY",s);
145 41 : if(s.length()>0) {
146 14 : u.setEnergy(s);
147 : }
148 41 : if(u.getEnergyString().length()>0 && u.getEnergyString()=="kj/mol") {
149 27 : log.printf(" energy: %s\n",u.getEnergyString().c_str());
150 14 : } else if(u.getEnergyString().length()>0 && u.getEnergyString()!="kj/mol") {
151 12 : log.printf(" energy: %s = %g kj/mol\n",u.getEnergyString().c_str(),u.getEnergy());
152 : } else {
153 2 : log.printf(" energy: %g kj/mol\n",u.getEnergy());
154 : }
155 :
156 : s="";
157 82 : parse("TIME",s);
158 41 : if(s.length()>0) {
159 14 : u.setTime(s);
160 : }
161 41 : if(u.getTimeString().length()>0 && u.getTimeString()=="ps") {
162 35 : log.printf(" time: %s\n",u.getTimeString().c_str());
163 6 : } else if(u.getTimeString().length()>0 && u.getTimeString()!="ps") {
164 4 : log.printf(" time: %s = %g ps\n",u.getTimeString().c_str(),u.getTime());
165 : } else {
166 2 : log.printf(" time: %g ps\n",u.getTime());
167 : }
168 :
169 : s="";
170 82 : parse("CHARGE",s);
171 41 : if(s.length()>0) {
172 3 : u.setCharge(s);
173 : }
174 41 : if(u.getChargeString().length()>0 && u.getChargeString()=="e") {
175 39 : log.printf(" charge: %s\n",u.getChargeString().c_str());
176 2 : } else if(u.getChargeString().length()>0 && u.getChargeString()!="e") {
177 0 : log.printf(" charge: %s = %g e\n",u.getChargeString().c_str(),u.getCharge());
178 : } else {
179 2 : log.printf(" charge: %g e\n",u.getCharge());
180 : }
181 :
182 : s="";
183 82 : parse("MASS",s);
184 41 : if(s.length()>0) {
185 2 : u.setMass(s);
186 : }
187 41 : if(u.getMassString().length()>0 && u.getMassString()=="amu") {
188 40 : log.printf(" mass: %s\n",u.getMassString().c_str());
189 1 : } else if(u.getMassString().length()>0 && u.getMassString()!="amu") {
190 0 : log.printf(" mass: %s = %g amu\n",u.getMassString().c_str(),u.getMass());
191 : } else {
192 1 : log.printf(" mass: %g amu\n",u.getMass());
193 : }
194 :
195 41 : bool natural=false;
196 41 : parseFlag("NATURAL",natural);
197 :
198 41 : checkRead();
199 :
200 41 : if(natural) {
201 7 : log.printf(" using natural units\n");
202 : } else {
203 34 : log.printf(" using physical units\n");
204 : }
205 41 : plumed.setUnits(natural,u);
206 : // printed after setting the units, so that it is in the new units
207 41 : log.printf(" inside PLUMED, Boltzmann constant is %g\n",getKBoltzmann());
208 41 : }
209 :
210 : }
211 : }
|
