git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@14967 f3b2605a-c512-4ea7-a41b-209d697bcdaa

doc/src/units.txt

@@ -0,0 +1,221 @@
+"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c
+
+:link(lws,http://lammps.sandia.gov)
+:link(ld,Manual.html)
+:link(lc,Section_commands.html#comm)
+
+:line
+
+units command :h3
+
+[Syntax:]
+
+units style :pre
+
+style = {lj} or {real} or {metal} or {si} or {cgs} or {electron} or {micro} or {nano} :ul
+
+[Examples:]
+
+units metal
+units lj :pre
+
+[Description:]
+
+This command sets the style of units used for a simulation.  It
+determines the units of all quantities specified in the input script
+and data file, as well as quantities output to the screen, log file,
+and dump files.  Typically, this command is used at the very beginning
+of an input script.
+
+For all units except {lj}, LAMMPS uses physical constants from
+www.physics.nist.gov.  For the definition of Kcal in real units,
+LAMMPS uses the thermochemical calorie = 4.184 J.
+
+The choice you make for units simply sets some internal conversion
+factors within LAMMPS.  This means that any simulation you perform for
+one choice of units can be duplicated with any other unit setting
+LAMMPS supports.  In this context "duplicate" means the particles will
+have identical trajectories and all output generated by the simulation
+will be identical.  This will be the case for some number of timesteps
+until round-off effects accumulate, since the conversion factors for
+two different unit systems are not identical to infinite precision.
+
+To perform the same simulation in a different set of units you must
+change all the unit-based input parameters in your input script and
+other input files (data file, potential files, etc) correctly to the
+new units.  And you must correctly convert all output from the new
+units to the old units when comparing to the original results.  That
+is often not simple to do.
+
+:line
+
+For style {lj}, all quantities are unitless.  Without loss of
+generality, LAMMPS sets the fundamental quantities mass, sigma,
+epsilon, and the Boltzmann constant = 1.  The masses, distances,
+energies you specify are multiples of these fundamental values.  The
+formulas relating the reduced or unitless quantity (with an asterisk)
+to the same quantity with units is also given.  Thus you can use the
+mass & sigma & epsilon values for a specific material and convert the
+results from a unitless LJ simulation into physical quantities.
+
+mass = mass or m
+distance = sigma, where x* = x / sigma
+time = tau, where t* = t (epsilon / m / sigma^2)^1/2
+energy = epsilon, where E* = E / epsilon
+velocity = sigma/tau, where v* = v tau / sigma
+force = epsilon/sigma, where f* = f sigma / epsilon
+torque = epsilon, where t* = t / epsilon
+temperature = reduced LJ temperature, where T* = T Kb / epsilon
+pressure = reduced LJ pressure, where P* = P sigma^3 / epsilon
+dynamic viscosity = reduced LJ viscosity, where eta* = eta sigma^3 / epsilon / tau
+charge = reduced LJ charge, where q* = q / (4 pi perm0 sigma epsilon)^1/2
+dipole = reduced LJ dipole, moment where *mu = mu / (4 pi perm0 sigma^3 epsilon)^1/2
+electric field = force/charge, where E* = E (4 pi perm0 sigma epsilon)^1/2 sigma / epsilon 
+density = mass/volume, where rho* = rho sigma^dim :ul
+
+Note that for LJ units, the default mode of thermodyamic output via
+the "thermo_style"_thermo_style.html command is to normalize all
+extensive quantities by the number of atoms.  E.g. potential energy is
+extensive because it is summed over atoms, so it is output as
+energy/atom.  Temperature is intensive since it is already normalized
+by the number of atoms, so it is output as-is.  This behavior can be
+changed via the "thermo_modify norm"_thermo_modify.html command.
+
+For style {real}, these are the units:
+
+mass = grams/mole
+distance = Angstroms
+time = femtoseconds
+energy = Kcal/mole 
+velocity = Angstroms/femtosecond 
+force = Kcal/mole-Angstrom
+torque = Kcal/mole
+temperature = Kelvin
+pressure = atmospheres
+dynamic viscosity = Poise
+charge = multiple of electron charge (1.0 is a proton)
+dipole = charge*Angstroms
+electric field = volts/Angstrom 
+density = gram/cm^dim :ul
+
+For style {metal}, these are the units:
+
+mass = grams/mole
+distance = Angstroms
+time = picoseconds
+energy = eV
+velocity = Angstroms/picosecond 
+force = eV/Angstrom
+torque = eV
+temperature = Kelvin
+pressure = bars
+dynamic viscosity = Poise
+charge = multiple of electron charge (1.0 is a proton)
+dipole = charge*Angstroms
+electric field = volts/Angstrom
+density = gram/cm^dim :ul
+
+For style {si}, these are the units:
+
+mass = kilograms
+distance = meters
+time = seconds
+energy = Joules
+velocity = meters/second
+force = Newtons
+torque = Newton-meters
+temperature = Kelvin
+pressure = Pascals
+dynamic viscosity = Pascal*second
+charge = Coulombs (1.6021765e-19 is a proton)
+dipole = Coulombs*meters
+electric field = volts/meter 
+density = kilograms/meter^dim :ul
+
+For style {cgs}, these are the units:
+
+mass = grams
+distance = centimeters
+time = seconds
+energy = ergs
+velocity = centimeters/second
+force = dynes
+torque = dyne-centimeters
+temperature = Kelvin
+pressure = dyne/cm^2 or barye = 1.0e-6 bars
+dynamic viscosity = Poise
+charge = statcoulombs or esu (4.8032044e-10 is a proton)
+dipole = statcoul-cm = 10^18 debye
+electric field = statvolt/cm or dyne/esu 
+density = grams/cm^dim :ul
+
+For style {electron}, these are the units:
+
+mass = atomic mass units
+distance = Bohr
+time = femtoseconds
+energy = Hartrees
+velocity = Bohr/atomic time units \[1.03275e-15 seconds\]
+force = Hartrees/Bohr
+temperature = Kelvin
+pressure = Pascals
+charge = multiple of electron charge (1.0 is a proton)
+dipole moment = Debye
+electric field = volts/cm :ul
+
+For style {micro}, these are the units:
+
+mass = picograms
+distance = micrometers
+time = microseconds
+energy = picogram-micrometer^2/microsecond^2
+velocity = micrometers/microsecond
+force = picogram-micrometer/microsecond^2
+torque = picogram-micrometer^2/microsecond^2
+temperature = Kelvin
+pressure = picogram/(micrometer-microsecond^2)
+dynamic viscosity = picogram/(micrometer-microsecond)
+charge = picocoulombs (1.6021765e-7 is a proton)
+dipole = picocoulomb-micrometer
+electric field = volt/micrometer 
+density = picograms/micrometer^dim :ul
+
+For style {nano}, these are the units:
+
+mass = attograms
+distance = nanometers
+time = nanoseconds
+energy = attogram-nanometer^2/nanosecond^2
+velocity = nanometers/nanosecond
+force = attogram-nanometer/nanosecond^2
+torque = attogram-nanometer^2/nanosecond^2
+temperature = Kelvin
+pressure = attogram/(nanometer-nanosecond^2)
+dynamic viscosity = attogram/(nanometer-nanosecond)
+charge = multiple of electron charge (1.0 is a proton)
+dipole = charge-nanometer
+electric field = volt/nanometer 
+density = attograms/nanometer^dim :ul
+
+The units command also sets the timestep size and neighbor skin
+distance to default values for each style:
+
+For style {lj} these are dt = 0.005 tau and skin = 0.3 sigma.
+For style {real} these are dt = 1.0 fmsec and skin = 2.0 Angstroms.
+For style {metal} these are dt = 0.001 psec and skin = 2.0 Angstroms.
+For style {si} these are dt = 1.0e-8 sec and skin = 0.001 meters.
+For style {cgs} these are dt = 1.0e-8 sec and skin = 0.1 cm.
+For style {electron} these are dt = 0.001 fmsec and skin = 2.0 Bohr. 
+For style {micro} these are dt = 2.0 microsec and skin = 0.1 micrometers.
+For style {nano} these are dt = 0.00045 nanosec and skin = 0.1 nanometers. :ul
+
+[Restrictions:]
+
+This command cannot be used after the simulation box is defined by a
+"read_data"_read_data.html or "create_box"_create_box.html command.
+
+[Related commands:] none
+
+[Default:]
+
+units lj :pre