Units
*****

Tip:

  For complete examples that use "scm.base" in context, see Python
  Examples.

class Units

   A utility class containing methods for units conversions.

   Simple example usage:

      from scm.base import Units
      import numpy as np

      energies_in_hartree = np.array([1,2,3])
      energies_in_ev = energies_in_hartree * Units.conversion_factor("Hartree", "eV")

      pressure_in_atm = 1.0
      pressure_in_kpascal = pressure_in_atm * Units.conversion_factor('atm', 'kPascal')

   classmethod conversion_factor(from_unit: str, to_unit: str) -> float

      Returns the conversion factor between two units.

      Parameters:
         * from_unit (str): The unit you want to convert from.

         * to_unit (str): The unit you want to convert to.

      Returns:
         * float: The conversion factor for converting *from_unit* to
           *to_unit*.

      Raises:
         * UnitsError: If either *from_unit* or *to_unit* is not
           supported/recognized or if you are trying to perform a
           conversion between incompatible units..

      Examples:

         >>> from scm.base import Units

         >>> Units.conversion_factor("m", "km")
         0.001

   classmethod get_canonical_name(alt: str) -> str

      Returns the canonical unit name (e.g. "get_canonical_name('m')
      -> 'meter'" ). Will throw on ambiguous result if there is no
      exact match.

   classmethod get_label(quantity: str) -> List[str]

      Returns the unicode label of the unit. (e.g.
      "get_label('angstrom') -> 'Å'" ).

   classmethod get_quantities() -> List[str]

      Returns all defined quantities. Quantities are things like
      'LENGTH', 'ENERGY' or 'MASS'.

   classmethod get_units(quantity: str) -> List[str]

      Returns all units associated with a quantity.

   classmethod units_summary_string() -> str

      Returns a string containing a nicely formatted table of all the
      units available.

class UnitsError

   Error thrown for unrecognized units or illegal conversions.


List of available units
=======================

To see the list of available units, you can use the
"units_summary_string()". Here is the output of
"print(Units.units_summary_string())":

   ======================
   Quantity: ACCELERATION
   ======================

   unit name                     label
   -----------------------------------

   angstrom/fs2                  Å/fs²


   ===============
   Quantity: ANGLE
   ===============

   unit name                     label
   -----------------------------------

   degree                        °
   rad                           rad
   grad                          grad
   turn                          tr


   =================
   Quantity: CURRENT
   =================

   unit name                     label
   -----------------------------------

   ehartree/hbar                 𝑒Ha/ℏ
   ampere                        A
   mampere                       mA
   uampere                       μA


   =================
   Quantity: DENSITY
   =================

   unit name                     label
   -----------------------------------

   dalton/bohr3                  Da/Bohr³
   kg/m3                         kg/m³
   g/cm3                         g/cm³
   kgl                           kg/L


   ================
   Quantity: DIPOLE
   ================

   unit name                     label
   -----------------------------------

   ebohr                         𝑒Bohr
   coulombmeter                  Cm
   debye                         D


   =======================
   Quantity: ELECTRICFIELD
   =======================

   unit name                     label
   -----------------------------------

   hartree/ebohr                 Ha/𝑒Bohr
   volt/angstrom                 V/Å
   volt/meter                    V/m


   ===========================
   Quantity: ELECTRICPOTENTIAL
   ===========================

   unit name                     label
   -----------------------------------

   volt                          V


   ================
   Quantity: ENERGY
   ================

   unit name                     label
   -----------------------------------

   hartree                       Ha
   rydberg                       Ry
   joule                         J
   kjoule                        kJ
   ev                            eV
   kcalmol                       kcal/mol
   kjmol                         kJ/mol
   cm-1                          cm⁻¹
   mhz                           MHz
   thz                           THz


   ================
   Quantity: FORCES
   ================

   unit name                     label
   -----------------------------------

   hartree/angstrom              Ha/Å
   hartree/meter                 Ha/m
   hartree/bohr                  Ha/Bohr
   rydberg/angstrom              Ry/Å
   rydberg/meter                 Ry/m
   rydberg/bohr                  Ry/Bohr
   joule/angstrom                J/Å
   joule/m                       N
   joule/bohr                    J/Bohr
   kjoule/angstrom               kJ/Å
   kjoule/meter                  kJ/m
   kjoule/bohr                   kJ/Bohr
   ev/angstrom                   eV/Å
   ev/meter                      eV/m
   ev/bohr                       eV/Bohr
   kcalmol/angstrom              kcal/mol/Å
   kcalmol/meter                 kcal/mol/m
   kcalmol/bohr                  kcal/mol/Bohr
   kjmol/angstrom                kJ/mol/Å
   kjmol/meter                   kJ/mol/m
   kjmol/bohr                    kJ/mol/Bohr
   cm-1/angstrom                 cm⁻¹/Å
   cm-1/meter                    cm⁻¹/m
   cm-1/bohr                     cm⁻¹/Bohr
   mhz/angstrom                  MHz/Å
   mhz/meter                     MHz/m
   mhz/bohr                      MHz/Bohr
   thz/angstrom                  THz/Å
   thz/meter                     THz/m
   thz/bohr                      THz/Bohr


   ================
   Quantity: LENGTH
   ================

   unit name                     label
   -----------------------------------

   bohr                          Bohr
   pm                            pm
   angstrom                      Å
   nm                            nm
   cm                            cm
   dm                            dm
   meter                         m


   =======================
   Quantity: MAGNETICFIELD
   =======================

   unit name                     label
   -----------------------------------

   gauss                         G
   tesla                         T
   aumagsi                       a.u. (mag SI)


   ==============
   Quantity: MASS
   ==============

   unit name                     label
   -----------------------------------

   dalton                        Da
   erestmass                     mₑ
   proton                        mₚ
   g                             g
   kg                            kg


   =========================
   Quantity: MOMENTOFINERTIA
   =========================

   unit name                     label
   -----------------------------------

   kgm2                          kgm²


   ==================
   Quantity: PRESSURE
   ==================

   unit name                     label
   -----------------------------------

   kpascal                       kPa
   mpascal                       MPa
   gpascal                       GPa
   bar                           bar
   mbar                          mbar
   kbar                          kbar
   atm                           atm
   torr                          Torr
   hartree/angstrom3             Ha/Å³
   hartree/meter3                Ha/m³
   hartree/bohr3                 Ha/Bohr³
   rydberg/angstrom3             Ry/Å³
   rydberg/meter3                Ry/m³
   rydberg/bohr3                 Ry/Bohr³
   joule/angstrom3               J/Å³
   pascal                        Pa
   joule/bohr3                   J/Bohr³
   kjoule/angstrom3              kJ/Å³
   kjoule/meter3                 kJ/m³
   kjoule/bohr3                  kJ/Bohr³
   ev/angstrom3                  eV/Å³
   ev/meter3                     eV/m³
   ev/bohr3                      eV/Bohr³
   kcalmol/angstrom3             kcal/mol/Å³
   kcalmol/meter3                kcal/mol/m³
   kcalmol/bohr3                 kcal/mol/Bohr³
   kjmol/angstrom3               kJ/mol/Å³
   kjmol/meter3                  kJ/mol/m³
   kjmol/bohr3                   kJ/mol/Bohr³
   cm-1/angstrom3                cm⁻¹/Å³
   cm-1/meter3                   cm⁻¹/m³
   cm-1/bohr3                    cm⁻¹/Bohr³
   mhz/angstrom3                 MHz/Å³
   mhz/meter3                    MHz/m³
   mhz/bohr3                     MHz/Bohr³
   thz/angstrom3                 THz/Å³
   thz/meter3                    THz/m³
   thz/bohr3                     THz/Bohr³


   ==========================
   Quantity: RECIPROCALLENGTH
   ==========================

   unit name                     label
   -----------------------------------

   bohr1                         Bohr⁻¹
   meter1                        m⁻¹
   angstrom1                     Å⁻¹
   nm1                           nm⁻¹


   ===================
   Quantity: SHIELDING
   ===================

   unit name                     label
   -----------------------------------

   ppm                           ppm


   ===================
   Quantity: STIFFNESS
   ===================

   unit name                     label
   -----------------------------------

   hartree/angstrom2             Ha/Å²
   hartree/meter2                Ha/m²
   hartree/bohr2                 Ha/Bohr²
   rydberg/angstrom2             Ry/Å²
   rydberg/meter2                Ry/m²
   rydberg/bohr2                 Ry/Bohr²
   joule/angstrom2               J/Å²
   joule/m2                      J/m²
   joule/bohr2                   J/Bohr²
   kjoule/angstrom2              kJ/Å²
   kjoule/meter2                 kJ/m²
   kjoule/bohr2                  kJ/Bohr²
   ev/angstrom2                  eV/Å²
   ev/meter2                     eV/m²
   ev/bohr2                      eV/Bohr²
   kcalmol/angstrom2             kcal/mol/Å²
   kcalmol/meter2                kcal/mol/m²
   kcalmol/bohr2                 kcal/mol/Bohr²
   kjmol/angstrom2               kJ/mol/Å²
   kjmol/meter2                  kJ/mol/m²
   kjmol/bohr2                   kJ/mol/Bohr²
   cm-1/angstrom2                cm⁻¹/Å²
   cm-1/meter2                   cm⁻¹/m²
   cm-1/bohr2                    cm⁻¹/Bohr²
   mhz/angstrom2                 MHz/Å²
   mhz/meter2                    MHz/m²
   mhz/bohr2                     MHz/Bohr²
   thz/angstrom2                 THz/Å²
   thz/meter2                    THz/m²
   thz/bohr2                     THz/Bohr²


   =====================
   Quantity: TEMPERATURE
   =====================

   unit name                     label
   -----------------------------------

   kelvin                        K
   celsius                       °C
   fahrenheit                    °F


   ==============
   Quantity: TIME
   ==============

   unit name                     label
   -----------------------------------

   s                             s
   ms                            ms
   us                            μs
   ns                            ns
   ps                            ps
   fs                            fs
   hartree_au_time               ℏ/Ha
   rydberg_au_time               ℏ/Ry
   hr                            hr
   min                           min


   ==================
   Quantity: VELOCITY
   ==================

   unit name                     label
   -----------------------------------

   bohr/fs                       Bohr/fs


   ================
   Quantity: VOLUME
   ================

   unit name                     label
   -----------------------------------

   bohr3                         Bohr³
   angstrom3                     Å³
   m3                            m³
