16. Constants and unit conversion — MDAnalysis.units

The base units of MDAnalysis trajectories are the Å (ångström) for length and ps (pico second) for time. By default, all positions are in Å and all times are in ps, regardless of how the MD code stored trajectory data. By default, MDAnalysis converts automatically to the MDAnalysis units when reading trajectories and converts back when writing. This makes it possible to write scripts that can be agnostic of the specifics of how a particular MD code stores trajectory data. Other base units are listed in the table on Base units in MDAnalysis as encoded in MDANALYSIS_BASE_UNITS.

Base units in MDAnalysis as encoded in MDANALYSIS_BASE_UNITS

quantity	unit	SI units
length	Å	\(10^{-10}\) m
time	ps	\(10^{-12}\) s
energy	kJ/mol	\(1.66053892103219 \times 10^{-21}\) J
charge	\(e\)	\(1.602176565 \times 10^{-19}\) As
force	kJ/(mol·Å)	\(1.66053892103219 \times 10^{-11}\) J/m
speed	Å/ps	\(100\) m/s

16.1. Implementation notes

All conversions with convert() are carried out in a simple fashion: the conversion factor \(f_{b,b'}\) from the base unit \(b\) to another unit \(b'\) is precomputed and stored (see Data). The numerical value of a quantity in unit \(b\) is \(X/b\) (e.g. for \(X = 1.23\,\mathrm{ps}\), the numerical value is \(X/\mathrm{ps} = 1.23\)). [2]

The new numerical value \(X'/b'\) of the quantity (in units of \(b'\)) is then

\[X'/b' = f_{b,b'} X/b\]

The function get_conversion_factor() returns the appropriate factor \(f_{b,b'}\).

Conversion between different units is always carried out via the base unit as an intermediate step:

x is in u1: from u1 to b:  x'  = x  / factor[u1]
            from b  to u2: x'' = x' * factor[u2]
so f[u1,u2] = factor[u2]/factor[u1]

16.1.1. Conversions

Examples for how to calculate some of the conversion factors that are hard-coded in units (see Data).

density:

Base unit is \(\mathrm{Å}^{-3}\):

n/x = n/A**3 * densityUnit_factor[x]

Example for how to calculate the conversion factor \(f_{\mathrm{Å}^{-3},\mathrm{nm}^{-3}}\) from \(\mathrm{Å}^{-3}\) to \(\mathrm{nm}^{-3}\):

\[f_{\mathrm{Å}^{-3},\mathrm{nm}^{-3}} = \frac{1\,\mathrm{nm}^{-3}}{1\,\mathrm{Å}^{-3}} = \frac{(10\,\mathrm{Å})^{-3}}{1\,\mathrm{Å}^{-3}} = 10^{-3}\]

concentration:

Example for how to convert the conversion factor to Molar (mol/l):

factor = 1 A**-3 / (N_Avogadro * (10**-9 dm)**-3)

relative to a density rho0 in \(g/cm^3\):

M(H2O) = 18 g/mol   Molar mass of water

factor = 1/(1e-24 * N_Avogadro / M(H2O))

from \(\rho/\rho_0 = n/(N_A * M^{-1}) / \rho_0\)

where \([n] = 1/Volume\), \([\rho] = mass/Volume\)

Note

In the future we might move towards using the Quantities package or scipy.constants.

16.2. Functions

MDAnalysis.units.get_conversion_factor(unit_type, u1, u2)

generate the conversion factor u1 -> u2 by using the base unit as an intermediate

f[u1 -> u2] = factor[u2]/factor[u1]

Conversion of \(X\) (in u1) to \(X'\) (in u2):

\(X'\) = conversion_factor * \(X\)

MDAnalysis.units.convert(x, u1, u2)

Convert value x in unit u1 to new value in u2.

Returns:

Converted value.

Return type:

float

Raises:

ValueError – The units are not known or if one attempts to convert between incompatible units.

16.3. Data

MDAnalysis.units.MDANALYSIS_BASE_UNITS = {'charge': 'e', 'energy': 'kJ/mol', 'force': 'kJ/(mol*A)', 'length': 'A', 'speed': 'A/ps', 'time': 'ps'}

Lookup table for base units in MDAnalysis by unit type.

MDAnalysis.units.constants = {'Boltzmann_constant': 0.008314462159, 'N_Avogadro': 6.02214129e+23, 'calorie': 4.184, 'electric_constant': 0.00552635, 'elementary_charge': 1.602176565e-19}

Values of physical constants are taken from CODATA 2010 at NIST. The thermochemical calorie is defined in the ISO 80000-5:2007 standard and is also listed in the NIST Guide to SI: Appendix B.8: Factors for Units.

Added in version 0.9.0.

MDAnalysis.units.lengthUnit_factor = {'A': 1.0, 'Angstrom': 1.0, 'angstrom': 1.0, 'femtometer': 100000.0, 'fm': 100000.0, 'nanometer': 0.1, 'nm': 0.1, 'picometer': 100.0, 'pm': 100.0, 'Å': 1.0}

The basic unit of length in MDAnalysis is the Angstrom. Conversion factors between the base unit and other lengthUnits x are stored. Conversions follow L/x = L/Angstrom * lengthUnit_factor[x]. x can be nm/nanometer or fm.

MDAnalysis.units.water = {'MolarMass': 18.016, 'SPC': 0.985, 'TIP3P': 1.002, 'TIP4P': 1.001, 'exp': 0.997}

water density values at T=298K, P=1atm [1].

model	g cm**-3
SPC	0.985(1)
TIP3P	1.002(1)
TIP4P	1.001(1)
exp	0.997

and molar mass 18.016 g mol**-1.

MDAnalysis.units.densityUnit_factor = {'A^{-3}': 1.0, 'Angstrom^{-3}': 1.0, 'Molar': 1660.5389210321898, 'SPC': 30.37184690488927, 'TIP3P': 29.85655608913766, 'TIP4P': 29.886382818497438, 'nanometer^{-3}': 1000.0, 'nm^{-3}': 1000.0, 'water': 30.00628806551247, 'Å^{-3}': 1.0}

The basic unit for densities is Angstrom**(-3), i.e. the volume per molecule in A**3. Especially for water it can be convenient to measure the density relative to bulk, and hence a number of values are pre-stored in water.

MDAnalysis.units.timeUnit_factor = {'AKMA': 20.45482949774598, 'femtosecond': 1000.0, 'fs': 1000.0, 'microsecond': 1e-06, 'millisecond': 1e-09, 'ms': 1e-09, 'nanosecond': 0.001, 'ns': 0.001, 'picosecond': 1.0, 'ps': 1.0, 's': 1e-12, 'sec': 1e-12, 'second': 1e-12, 'us': 1e-06, 'μs': 1e-06}

For time, the basic unit is ps; in particular CHARMM’s 1 AKMA time unit = 4.888821E-14 sec is supported.

MDAnalysis.units.speedUnit_factor = {'A/AKMA': 0.04888821, 'A/fs': 1000.0, 'A/ms': 1e-09, 'A/ps': 1.0, 'A/us': 1e-06, 'Angstrom/AKMA': 0.04888821, 'Angstrom/femtosecond': 1000.0, 'Angstrom/fs': 1000.0, 'Angstrom/microsecond': 1e-06, 'Angstrom/millisecond': 1e-09, 'Angstrom/ms': 1e-09, 'Angstrom/picosecond': 1.0, 'Angstrom/ps': 1.0, 'Angstrom/us': 1e-06, 'Angstrom/μs': 1e-06, 'angstrom/femtosecond': 1000.0, 'angstrom/fs': 1000.0, 'angstrom/microsecond': 1e-06, 'angstrom/millisecond': 1e-09, 'angstrom/ms': 1e-09, 'angstrom/picosecond': 1.0, 'angstrom/us': 1e-06, 'angstrom/μs': 1e-06, 'm/s': 100.0, 'nanometer/picosecond': 0.1, 'nanometer/ps': 0.1, 'nm/ns': 100.0, 'nm/ps': 0.1, 'pm/ps': 100.0, 'Å/ps': 1.0}

For speed, the basic unit is Angstrom/ps.

MDAnalysis.units.forceUnit_factor = {'J/m': 1.66053892103219e-11, 'N': 1.66053892103219e-11, 'Newton': 1.66053892103219e-11, 'kJ/(mol*A)': 1.0, 'kJ/(mol*Angstrom)': 1.0, 'kJ/(mol*nm)': 10.0, 'kJ/(mol*Å)': 1.0, 'kcal/(mol*Angstrom)': 0.2390057361376673}

For force the basic unit is kJ/(mol*Angstrom).

MDAnalysis.units.chargeUnit_factor = {'Amber': 18.2223, 'As': 1.602176565e-19, 'C': 1.602176565e-19, 'e': 1.0}

Charge is measured in multiples of the electron charge e, with the value elementary_charge in constants. The conversion factor to Amber charge units is 18.2223.

Changed in version 0.9.0: Use CODATA 2010 value for elementary charge, which differs from the previously used value e = 1.602176487 x 10**(-19) C by 7.8000000e-27 C.

MDAnalysis.units.conversion_factor = {'charge': {'Amber': 18.2223, 'As': 1.602176565e-19, 'C': 1.602176565e-19, 'e': 1.0}, 'density': {'A^{-3}': 1.0, 'Angstrom^{-3}': 1.0, 'Molar': 1660.5389210321898, 'SPC': 30.37184690488927, 'TIP3P': 29.85655608913766, 'TIP4P': 29.886382818497438, 'nanometer^{-3}': 1000.0, 'nm^{-3}': 1000.0, 'water': 30.00628806551247, 'Å^{-3}': 1.0}, 'energy': {'J': 1.66053892103219e-21, 'eV': 0.01036426919046959, 'kJ/mol': 1.0, 'kcal/mol': 0.2390057361376673}, 'force': {'J/m': 1.66053892103219e-11, 'N': 1.66053892103219e-11, 'Newton': 1.66053892103219e-11, 'kJ/(mol*A)': 1.0, 'kJ/(mol*Angstrom)': 1.0, 'kJ/(mol*nm)': 10.0, 'kJ/(mol*Å)': 1.0, 'kcal/(mol*Angstrom)': 0.2390057361376673}, 'length': {'A': 1.0, 'Angstrom': 1.0, 'angstrom': 1.0, 'femtometer': 100000.0, 'fm': 100000.0, 'nanometer': 0.1, 'nm': 0.1, 'picometer': 100.0, 'pm': 100.0, 'Å': 1.0}, 'speed': {'A/AKMA': 0.04888821, 'A/fs': 1000.0, 'A/ms': 1e-09, 'A/ps': 1.0, 'A/us': 1e-06, 'Angstrom/AKMA': 0.04888821, 'Angstrom/femtosecond': 1000.0, 'Angstrom/fs': 1000.0, 'Angstrom/microsecond': 1e-06, 'Angstrom/millisecond': 1e-09, 'Angstrom/ms': 1e-09, 'Angstrom/picosecond': 1.0, 'Angstrom/ps': 1.0, 'Angstrom/us': 1e-06, 'Angstrom/μs': 1e-06, 'angstrom/femtosecond': 1000.0, 'angstrom/fs': 1000.0, 'angstrom/microsecond': 1e-06, 'angstrom/millisecond': 1e-09, 'angstrom/ms': 1e-09, 'angstrom/picosecond': 1.0, 'angstrom/us': 1e-06, 'angstrom/μs': 1e-06, 'm/s': 100.0, 'nanometer/picosecond': 0.1, 'nanometer/ps': 0.1, 'nm/ns': 100.0, 'nm/ps': 0.1, 'pm/ps': 100.0, 'Å/ps': 1.0}, 'time': {'AKMA': 20.45482949774598, 'femtosecond': 1000.0, 'fs': 1000.0, 'microsecond': 1e-06, 'millisecond': 1e-09, 'ms': 1e-09, 'nanosecond': 0.001, 'ns': 0.001, 'picosecond': 1.0, 'ps': 1.0, 's': 1e-12, 'sec': 1e-12, 'second': 1e-12, 'us': 1e-06, 'μs': 1e-06}}

conversion_factor is used by get_conversion_factor() NOTE: any observable with a unit (i.e. one with an entry in the unit attribute) needs an entry in conversion_factor

MDAnalysis.units.unit_types = {'A': 'length', 'A/AKMA': 'speed', 'A/fs': 'speed', 'A/ms': 'speed', 'A/ps': 'speed', 'A/us': 'speed', 'AKMA': 'time', 'A^{-3}': 'density', 'Amber': 'charge', 'Angstrom': 'length', 'Angstrom/AKMA': 'speed', 'Angstrom/femtosecond': 'speed', 'Angstrom/fs': 'speed', 'Angstrom/microsecond': 'speed', 'Angstrom/millisecond': 'speed', 'Angstrom/ms': 'speed', 'Angstrom/picosecond': 'speed', 'Angstrom/ps': 'speed', 'Angstrom/us': 'speed', 'Angstrom/μs': 'speed', 'Angstrom^{-3}': 'density', 'As': 'charge', 'C': 'charge', 'J': 'energy', 'J/m': 'force', 'Molar': 'density', 'N': 'force', 'Newton': 'force', 'SPC': 'density', 'TIP3P': 'density', 'TIP4P': 'density', 'angstrom': 'length', 'angstrom/femtosecond': 'speed', 'angstrom/fs': 'speed', 'angstrom/microsecond': 'speed', 'angstrom/millisecond': 'speed', 'angstrom/ms': 'speed', 'angstrom/picosecond': 'speed', 'angstrom/us': 'speed', 'angstrom/μs': 'speed', 'e': 'charge', 'eV': 'energy', 'femtometer': 'length', 'femtosecond': 'time', 'fm': 'length', 'fs': 'time', 'kJ/(mol*A)': 'force', 'kJ/(mol*Angstrom)': 'force', 'kJ/(mol*nm)': 'force', 'kJ/(mol*Å)': 'force', 'kJ/mol': 'energy', 'kcal/(mol*Angstrom)': 'force', 'kcal/mol': 'energy', 'm/s': 'speed', 'microsecond': 'time', 'millisecond': 'time', 'ms': 'time', 'nanometer': 'length', 'nanometer/picosecond': 'speed', 'nanometer/ps': 'speed', 'nanometer^{-3}': 'density', 'nanosecond': 'time', 'nm': 'length', 'nm/ns': 'speed', 'nm/ps': 'speed', 'nm^{-3}': 'density', 'ns': 'time', 'picometer': 'length', 'picosecond': 'time', 'pm': 'length', 'pm/ps': 'speed', 'ps': 'time', 's': 'time', 'sec': 'time', 'second': 'time', 'us': 'time', 'water': 'density', 'μs': 'time', 'Å': 'length', 'Å/ps': 'speed', 'Å^{-3}': 'density'}

returns the type of unit for a known input unit. Note: Any unit must be unique because this dict is used to guess the unit type.

Type:

Generated lookup table (dict)

16.4. References and footnotes

[1]

William L. Jorgensen and Corky Jenson. Temperature dependence of tip3p, spc, and tip4p water from npt monte carlo simulations: seeking temperatures of maximum density. Journal of Computational Chemistry, 19(10):1179–1186, 1998. doi:https://doi.org/10.1002/(SICI)1096-987X(19980730)19:10<1179::AID-JCC6>3.0.CO;2-J.

Footnotes

[2]

One can also consider the conversion factor to carry units \(b'/b\), in which case the conversion formula would become

\[X' = f_{b,b'} X\]