.. _user-guide-units: |pyretis| units =============== |pyretis| simulations are always carried out with a consistent set of units. A system of units is defined by specifying the energy scale, :math:E, the length scale, :math:L, and the mass scale, :math:M. This implicitly defines the time scale, :math:T, as .. math:: T = \sqrt{\frac{M L^2}{E}}. The charges are typically specified in units of electron charges or in Coulombs. In |pyretis| the charges are internally scaled with the factor :math:\frac{1}{\sqrt{4 \pi \varepsilon_0}} (where the units of :math:\varepsilon_0 is consistent with the defined :math:E, :math:L and :math:M). This means that the Coulomb constant is implicitly contained within the charges in the internal computations. In |pyretis|, several systems of units are defined and you may also define your own units. The choice of a system of units will define the units used for input parameters. The different systems of units defined in |pyretis| are described in the following :ref:section  and the creation of custom systems are :ref:also described . In the |pyretis| library, the units are defined in the :py:mod:pyretis.core.units module. The defined constants can be displayed by, .. code-block:: python from pyretis.core.units import CONSTANTS print('All constants':) print(CONSTANTS) print('The Boltzmann constant:') print(CONSTANTS['kB']) .. _user-units-system: System of units in |pyretis| ---------------------------- The systems of units that are defined in |pyretis| are: - lj: A Lennard-Jones type of units. - real: A system of units similar to the LAMMPS [1]_ unit real. - metal: A system of units similar to the LAMMPS [1]_ unit metal. - au: Atomic units. [2]_ - electron: A system of units similar to the LAMMPS [1]_ unit electron. - si: A system of units similar to the LAMMPS [1]_ unit si. - gromacs: A system of units similar to the units used by GROMACS. [3]_ The different bases for the different units are given in the :ref:table of definitions  below. The system of units is defined by setting the units keyword to any of these units, e.g. .. code-block:: python units = real # or perhaps: units = metal # or even Lennard-Jones units: units = lj Setting the unit system will define the units used for input to |pyretis|. The units for the different systems are given in the :ref:table of input units  below. Note that the time unit is determined by the energy, length and mass scale and that **the input time step will be assumed to be given in internal units**. Conversion factors to more familiar units are given in the :ref:table on time units . If the initial configuration is given as a file (for instance in xyz format), then the system of units will be used to convert the configuration. That is, |pyretis| will assume that the configuration is given in the units specified by the file format (e.g. Ångström for positions in a xyz file). The coordinates read from initial configuration fill will be converted internally to the selected system of units. .. _table_unit_input: .. table:: Input units for different systems :class: table-striped table-hover +--------------+----------+---------+---------------+ | Unit system | Energy | Length | Mass | +==============+==========+=========+===============+ | lj | reduced | reduced | reduced | +--------------+----------+---------+---------------+ | real | kcal/mol | Å | g/mol | +--------------+----------+---------+---------------+ | gromacs | kJ/mol | nm | g/mol | +--------------+----------+---------+---------------+ | metal | eV | Å | g/mol | +--------------+----------+---------+---------------+ | au | hartree | bohr | electron mass | +--------------+----------+---------+---------------+ | electron | hartree | bohr | g/mol (amu) | +--------------+----------+---------+---------------+ | si | J | m | kg | +--------------+----------+---------+---------------+ For the lj system, the energy, length, mass, etc. are all given in reduced units. However, it still might be useful (for instance for trajectory output) to convert to other units. By default, the scales for the Lennard-Jones system of units corresponds to values for Argon. [4]_ These default units can be overridden explicitly by defining the length scale, mass scale and energy scale: .. code-block:: python units = lj units-base = {'length': (3.405, 'A'), 'mass': (39.948, 'g/mol'), 'energy': (119.8, 'kB')} However, again note that this will only influence how we interpret input and output configurations: all other output units for this system will still be in reduced Lennard-Jones units. The syntax for overriding and creating your own units are further described in the :ref:next section . .. _table_unit_systems: .. table:: Defining units for energy systems :class: table-striped table-hover +--------------+----------------+-------------+--------------------+ | Unit system | Energy unit | Length unit | Mass unit | +==============+================+=============+====================+ | lj | 0.238 kcal/mol | 0.3405 nm | 39.948 g/mol | +--------------+----------------+-------------+--------------------+ | real | 1 kcal/mol | 1 Å | 1 g/mol | +--------------+----------------+-------------+--------------------+ | gromacs | 1 kJ/mol | 1 nm | 1 g/mol | +--------------+----------------+-------------+--------------------+ | metal | 1 eV | 1 Å | 1 g/mol | +--------------+----------------+-------------+--------------------+ | au | 1 hartree | 1 bohr | 9.10938291e-31 kg | +--------------+----------------+-------------+--------------------+ | electron | 1 hartree | 1 bohr | 1 g/mol | +--------------+----------------+-------------+--------------------+ | si | 1 J | 1 m | 1 kg | +--------------+----------------+-------------+--------------------+ These units are also used for the input and define the time unit. The time units are shown in :ref:the table below . Further, all system of units expect an input temperature in Kelvin (K) and all systems, except for si, expects a charge in units of electron charges. The si system uses here Coulomb as the unit of charge. The time units for the different energy systems are given in the table below. .. _table_unit_systems_time: .. table:: Time units and velocity conversions for energy systems :class: table-striped table-hover +--------------+--------------------+ | Unit system | Time unit | +==============+====================+ | lj | 2.15634977232 ps | +--------------+--------------------+ | real | 48.8882129084 fs | +--------------+--------------------+ | gromacs | 1.0 ps | +--------------+--------------------+ | metal | 10.1805056505 fs | +--------------+--------------------+ | au | 0.0241888423521 fs | +--------------+--------------------+ | electron | 1.03274987345 fs | +--------------+--------------------+ | si | 1.0 s | +--------------+--------------------+ The interpretation here is that if you are for instance using the system real and would like to have a time step equal to 0.5 fs, then the input time step should be 0.5 fs / 48.8882129084 fs which is approximately 0.010227. Another example: If you are using the system metal and set your time step to 0.1, then the time step will be approximately 1.018 fs. .. _user-units-custom: Defining your own system of units --------------------------------- Defining your own system of units is basically just a matter of choosing the energy, length and mass scales. Typically, this is done by setting the units keyword and defining the base units in the section :ref:Unit-system : .. code-block:: rst System ------ units = new-system Unit-system ----------- name = new-system length = (1.0, 'bohr') mass = (9.81e-31, 'kg') energy = (1.0, 'kcal/mol') charge = e Note again that this will influence how the input parameters are interpreted and that the input configuration files will be converted to the internal unit system. In the example above, a configuration read from a xyz-file will be converted from Ångström to Bohr for internal calculations. The syntax for specifying a new scale for a dimension is of form .. code-block:: python 'dimension' = (value, unit) Where the value is a number defining the scale and unit a text string which defines the unit to use. This text string is case-sensitive. For each dimension, |pyretis| defines a set of "known" units to choose from: Length: * A: Ångström. * nm: Nanometre. * bohr: Bohr radius. * m: Meter. Energy: * kcal: Kilocalorie. * kcal/mol: Kilocalorie per mol. * J: Joule. * J/mol: Joule per mol. * kJ/mol: Kilojoule per mol. * eV: Electronvolt. * hartree: Hartree (atomic unit of energy). Mass: * g/mol: Grams per mol, numerically equal to the atomic mass unit. * g: Gram. * kg: Kilogram. For the charge setting, there it is currently only possible to define the unit as either e (for the electron charge) or C (for Coulomb). References ---------- .. [1] The LAMMPS manual, http://lammps.sandia.gov/doc/units.html .. [2] https://en.wikipedia.org/wiki/Atomic_units .. [3] The GROMACS manual, tables 2.1 and 2.2 on page. 8, http://manual.gromacs.org/documentation/5.1.1/manual-5.1.1.pdf .. [4] Rowley et al., J. Comput. Phys., vol. 17, pp. 401-414, 1975, doi: http://dx.doi.org/10.1016/0021-9991