1.. index:: units
2
3units command
4=============
5
6Syntax
7""""""
8
9.. parsed-literal::
10
11   units style
12
13* style = *lj* or *real* or *metal* or *si* or *cgs* or *electron* or *micro* or *nano*
14
15Examples
16""""""""
17
18.. code-block:: LAMMPS
19
20   units metal
21   units lj
22
23Description
24"""""""""""
25
26This command sets the style of units used for a simulation.  It
27determines the units of all quantities specified in the input script
28and data file, as well as quantities output to the screen, log file,
29and dump files.  Typically, this command is used at the very beginning
30of an input script.
31
32For all units except *lj*, LAMMPS uses physical constants from
33www.physics.nist.gov.  For the definition of Kcal in real units,
34LAMMPS uses the thermochemical calorie = 4.184 J.
35
36The choice you make for units simply sets some internal conversion
37factors within LAMMPS.  This means that any simulation you perform for
38one choice of units can be duplicated with any other unit setting
39LAMMPS supports.  In this context "duplicate" means the particles will
40have identical trajectories and all output generated by the simulation
41will be identical.  This will be the case for some number of timesteps
42until round-off effects accumulate, since the conversion factors for
43two different unit systems are not identical to infinite precision.
44
45To perform the same simulation in a different set of units you must
46change all the unit-based input parameters in your input script and
47other input files (data file, potential files, etc) correctly to the
48new units.  And you must correctly convert all output from the new
49units to the old units when comparing to the original results.  That
50is often not simple to do.
51
52Potential or table files may have a ``UNITS:`` tag included in the
53first line indicating the unit style those files were created for.
54If the tag exists, its value will be compared to the chosen unit style
55and LAMMPS will stop with an error message if there is a mismatch.
56In some select cases and for specific combinations of unit styles,
57LAMMPS is capable of automatically converting potential parameters
58from a file. In those cases, a warning message signaling that an
59automatic conversion has happened is printed to the screen.
60
61----------
62
63For style *lj*, all quantities are unitless.  Without loss of
64generality, LAMMPS sets the fundamental quantities mass, :math:`\sigma`,
65:math:`\epsilon`, and the Boltzmann constant :math:`k_B = 1`.  The
66masses, distances, energies you specify are multiples of these
67fundamental values.  The formulas relating the reduced or unitless
68quantity (with an asterisk) to the same quantity with units is also
69given.  Thus you can use the mass, :math:`\sigma`, and :math:`\epsilon`
70values for a specific material and convert the results from a unitless
71LJ simulation into physical quantities.  Please note that using
72these three properties as base, your unit of time has to conform
73to the relation :math:`\epsilon = \frac{m \sigma^2}{\tau^2}` since
74energy is a derived unit (in SI units you equivalently have the relation
75:math:`1\mathsf{J} = 1\frac{\mathsf{kg}\cdot\mathsf{m}^2}{\mathsf{s}^2}`).
76
77* mass = mass or :math:`m`, where :math:`M^* = \frac{M}{m}`
78* distance = :math:`\sigma`, where :math:`x^* = \frac{x}{\sigma}`
79* time = :math:`\tau`, where :math:`\tau^* = \tau \sqrt{\frac{\epsilon}{m \sigma^2}}`
80* energy = :math:`\epsilon`, where :math:`E^* = \frac{E}{\epsilon}`
81* velocity = :math:`\frac{\sigma}{\tau}`, where :math:`v^* = v \frac{\tau}{\sigma}`
82* force = :math:`\frac{\epsilon}{\sigma}`, where :math:`f^* = f \frac{\sigma}{\epsilon}`
83* torque = :math:`\epsilon`, where :math:`t^* = \frac{t}{\epsilon}`
84* temperature = reduced LJ temperature, where :math:`T^* = \frac{T k_B}{\epsilon}`
85* pressure = reduced LJ pressure, where :math:`p^* = p \frac{\sigma^3}{\epsilon}`
86* dynamic viscosity = reduced LJ viscosity, where :math:`\eta^* = \eta \frac{\sigma^3}{\epsilon\tau}`
87* charge = reduced LJ charge, where :math:`q^* = q \frac{1}{\sqrt{4 \pi \varepsilon_0 \sigma \epsilon}}`
88* dipole = reduced LJ dipole, moment where :math:`\mu^* = \mu \frac{1}{\sqrt{4 \pi \varepsilon_0 \sigma^3 \epsilon}}`
89* electric field = force/charge, where :math:`E^* = E \frac{\sqrt{4 \pi \varepsilon_0 \sigma \epsilon} \sigma}{\epsilon}`
90* density = mass/volume, where :math:`\rho^* = \rho \frac{\sigma^{dim}}{m}`
91
92Note that for LJ units, the default mode of thermodynamic output via
93the :doc:`thermo_style <thermo_style>` command is to normalize all
94extensive quantities by the number of atoms.  E.g. potential energy is
95extensive because it is summed over atoms, so it is output as
96energy/atom.  Temperature is intensive since it is already normalized
97by the number of atoms, so it is output as-is.  This behavior can be
98changed via the :doc:`thermo_modify norm <thermo_modify>` command.
99
100For style *real*, these are the units:
101
102* mass = grams/mole
103* distance = Angstroms
104* time = femtoseconds
105* energy = Kcal/mole
106* velocity = Angstroms/femtosecond
107* force = Kcal/mole-Angstrom
108* torque = Kcal/mole
109* temperature = Kelvin
110* pressure = atmospheres
111* dynamic viscosity = Poise
112* charge = multiple of electron charge (1.0 is a proton)
113* dipole = charge\*Angstroms
114* electric field = volts/Angstrom
115* density = gram/cm\^dim
116
117For style *metal*, these are the units:
118
119* mass = grams/mole
120* distance = Angstroms
121* time = picoseconds
122* energy = eV
123* velocity = Angstroms/picosecond
124* force = eV/Angstrom
125* torque = eV
126* temperature = Kelvin
127* pressure = bars
128* dynamic viscosity = Poise
129* charge = multiple of electron charge (1.0 is a proton)
130* dipole = charge\*Angstroms
131* electric field = volts/Angstrom
132* density = gram/cm\^dim
133
134For style *si*, these are the units:
135
136* mass = kilograms
137* distance = meters
138* time = seconds
139* energy = Joules
140* velocity = meters/second
141* force = Newtons
142* torque = Newton-meters
143* temperature = Kelvin
144* pressure = Pascals
145* dynamic viscosity = Pascal\*second
146* charge = Coulombs (1.6021765e-19 is a proton)
147* dipole = Coulombs\*meters
148* electric field = volts/meter
149* density = kilograms/meter\^dim
150
151For style *cgs*, these are the units:
152
153* mass = grams
154* distance = centimeters
155* time = seconds
156* energy = ergs
157* velocity = centimeters/second
158* force = dynes
159* torque = dyne-centimeters
160* temperature = Kelvin
161* pressure = dyne/cm\^2 or barye = 1.0e-6 bars
162* dynamic viscosity = Poise
163* charge = statcoulombs or esu (4.8032044e-10 is a proton)
164* dipole = statcoul-cm = 10\^18 debye
165* electric field = statvolt/cm or dyne/esu
166* density = grams/cm\^dim
167
168For style *electron*, these are the units:
169
170* mass = atomic mass units
171* distance = Bohr
172* time = femtoseconds
173* energy = Hartrees
174* velocity = Bohr/atomic time units [1.03275e-15 seconds]
175* force = Hartrees/Bohr
176* temperature = Kelvin
177* pressure = Pascals
178* charge = multiple of electron charge (1.0 is a proton)
179* dipole moment = Debye
180* electric field = volts/cm
181
182For style *micro*, these are the units:
183
184* mass = picograms
185* distance = micrometers
186* time = microseconds
187* energy = picogram-micrometer\^2/microsecond\^2
188* velocity = micrometers/microsecond
189* force = picogram-micrometer/microsecond\^2
190* torque = picogram-micrometer\^2/microsecond\^2
191* temperature = Kelvin
192* pressure = picogram/(micrometer-microsecond\^2)
193* dynamic viscosity = picogram/(micrometer-microsecond)
194* charge = picocoulombs (1.6021765e-7 is a proton)
195* dipole = picocoulomb-micrometer
196* electric field = volt/micrometer
197* density = picograms/micrometer\^dim
198
199For style *nano*, these are the units:
200
201* mass = attograms
202* distance = nanometers
203* time = nanoseconds
204* energy = attogram-nanometer\^2/nanosecond\^2
205* velocity = nanometers/nanosecond
206* force = attogram-nanometer/nanosecond\^2
207* torque = attogram-nanometer\^2/nanosecond\^2
208* temperature = Kelvin
209* pressure = attogram/(nanometer-nanosecond\^2)
210* dynamic viscosity = attogram/(nanometer-nanosecond)
211* charge = multiple of electron charge (1.0 is a proton)
212* dipole = charge-nanometer
213* electric field = volt/nanometer
214* density = attograms/nanometer\^dim
215
216The units command also sets the timestep size and neighbor skin
217distance to default values for each style:
218
219* For style *lj* these are dt = 0.005 :math:`\tau` and skin = 0.3 :math:`\sigma`.
220* For style *real* these are dt = 1.0 femtoseconds and skin = 2.0 Angstroms.
221* For style *metal* these are dt = 0.001 picoseconds and skin = 2.0 Angstroms.
222* For style *si* these are dt = 1.0e-8 seconds and skin = 0.001 meters.
223* For style *cgs* these are dt = 1.0e-8 seconds and skin = 0.1 centimeters.
224* For style *electron* these are dt = 0.001 femtoseconds and skin = 2.0 Bohr.
225* For style *micro* these are dt = 2.0 microseconds and skin = 0.1 micrometers.
226* For style *nano* these are dt = 0.00045 nanoseconds and skin = 0.1 nanometers.
227
228Restrictions
229""""""""""""
230
231This command cannot be used after the simulation box is defined by a
232:doc:`read_data <read_data>` or :doc:`create_box <create_box>` command.
233
234Related commands
235""""""""""""""""
236
237none
238
239
240Default
241"""""""
242
243.. code-block:: LAMMPS
244
245   units lj
246