doc/user/units.dox

   1 /*
   2 Highly Optimized Object-oriented Many-particle Dynamics -- Blue Edition
   3 (HOOMD-blue) Open Source Software License Copyright 2009-2014 The Regents of
   4 the University of Michigan All rights reserved.
   5
   6 HOOMD-blue may contain modifications ("Contributions") provided, and to which
   7 copyright is held, by various Contributors who have granted The Regents of the
   8 University of Michigan the right to modify and/or distribute such Contributions.
   9
  10 You may redistribute, use, and create derivate works of HOOMD-blue, in source
  11 and binary forms, provided you abide by the following conditions:
  12
  13 * Redistributions of source code must retain the above copyright notice, this
  14 list of conditions, and the following disclaimer both in the code and
  15 prominently in any materials provided with the distribution.
  16
  17 * Redistributions in binary form must reproduce the above copyright notice, this
  18 list of conditions, and the following disclaimer in the documentation and/or
  19 other materials provided with the distribution.
  20
  21 * All publications and presentations based on HOOMD-blue, including any reports
  22 or published results obtained, in whole or in part, with HOOMD-blue, will
  23 acknowledge its use according to the terms posted at the time of submission on:
  24 http://codeblue.umich.edu/hoomd-blue/citations.html
  25
  26 * Any electronic documents citing HOOMD-Blue will link to the HOOMD-Blue website:
  27 http://codeblue.umich.edu/hoomd-blue/
  28
  29 * Apart from the above required attributions, neither the name of the copyright
  30 holder nor the names of HOOMD-blue's contributors may be used to endorse or
  31 promote products derived from this software without specific prior written
  32 permission.
  33
  34 Disclaimer
  35
  36 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS ``AS IS'' AND
  37 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  38 WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND/OR ANY
  39 WARRANTIES THAT THIS SOFTWARE IS FREE OF INFRINGEMENT ARE DISCLAIMED.
  40
  41 IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
  42 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
  43 BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  44 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  45 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
  46 OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  47 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  48 */
  49
  50 /*! \page page_units Units
  51
  52 ## Units in HOOMD-blue
  53
  54 HOOMD-blue stores and computes all values in a system of generic, but fully self-consistent set of units.
  55 No conversion factors need to be applied to values at every step. For example, a value with units
  56 of force comes from dividing energy by distance. You may be familiar with this system of units
  57 as being referred to as reduced *Lennard-Jones* units. These will be more formally generalized here for
  58 application to all types of potentials in HOOMD-blue.
  59
  60 ## Fundamental Units
  61
  62 The three fundamental units are:
  63
  64 - distance - \f$\mathcal{D}\f$
  65 - energy - \f$\mathcal{E}\f$
  66 - mass - \f$\mathcal{M}\f$
  67
  68 All other units that appear in HOOMD-blue are derived from these. Values can be converted into any other system
  69 of units by assigning the desired units to \f$\mathcal{D}\f$, \f$\mathcal{E}\f$, and \f$\mathcal{M}\f$ and then
  70 multiplying by the appropriate conversion factors.
  71
  72 The standard *Lennard-Jones* symbols \f$ \sigma \f$ and \f$ \epsilon \f$ are intentionally not used in this
  73 document. When you assign a value to \f$ \epsilon \f$, for example, you are assigning it in units of energy:
  74 \f$ \epsilon = 5 \mathcal{E} \f$. Here, \f$ \epsilon \f$ is **NOT** the unit of energy. To understand this in a trivial case,
  75 consider a system with two particle types, there are three distinct \f$ \epsilon_{ij} \f$ values to set, and they cannot
  76 each be the unit of energy.
  77
  78 Floating point calculations are most precise when values are close to unity. It is generally best to choose a scale
  79 where particle diameters, energy well depths, particle masses are near 1.
  80
  81 ## Temperature (thermal energy)
  82
  83 The standard nomenclature in the literature regarding Lennard-Jones *reduced temperature*
  84 is generally not very precise or consistent. HOOMD-blue's parameter names unfortunately do not help that situation
  85 (maybe a later version will fix this). Formally, whenever HOOMD-blue asks for or reports a **temperature** \f$T\f$, the
  86 value is a thermal energy \f$T = k_\mathrm{B} T_\mathrm{actual}\f$ *in units of energy*. The value
  87 \f$k_\mathrm{B}\f$ is determined by your choice of real units for distance, energy, and mass.
  88
  89 ## Charge
  90
  91 The unit of charge used in HOOMD-blue is also reduced, but is not represented using just the 3 fundamental units -
  92 the permittivity of free space \f$ \varepsilon_0 \f$ is also present. The units of charge are:
  93 \f$ (4 \pi \varepsilon_0 \mathcal{D} \mathcal{E})^{1/2} \f$. Divide a given charge by this quantity to convert it into
  94 an input value for HOOMD-blue.
  95
  96 ## Common derived units
  97
  98 Here are some commonly used derived units:
  99
 100 - time - \f$\tau = \sqrt{\frac{\mathcal{M} \mathcal{D}^2}{\mathcal{E}}}\f$
 101 - volume - \f$ \mathcal{D}^3 \f$
 102 - velocity - \f$ \frac{\mathcal{D}}{\tau}\f$
 103 - momentum - \f$ \mathcal{M} \frac{\mathcal{D}}{\tau} \f$
 104 - acceleration - \f$ \frac{\mathcal{D}}{\tau^2}\f$
 105 - force - \f$ \frac{\mathcal{E}}{\mathcal{D}} \f$
 106 - pressure - \f$ \frac{\mathcal{E}}{\mathcal{D}^3} \f$
 107
 108 */