# pymatgen.core.units module

This module implements a FloatWithUnit, which is a subclass of float. It also defines supported units for some commonly used units for energy, length, temperature, time and charge. FloatWithUnit also support conversion to one another, and additions and subtractions perform automatic conversion if units are detected. An ArrayWithUnit is also implemented, which is a subclass of numpy’s ndarray with similar unit features.

class ArrayWithUnit(input_array, unit, unit_type=None)

  Bases: `numpy.ndarray`

  Subclasses numpy.ndarray to attach a unit type. Typically, you should use the pre-defined unit type subclasses such as EnergyArray, LengthArray, etc. instead of using ArrayWithFloatWithUnit directly.

  Supports conversion, addition and subtraction of the same unit type. E.g., 1 m + 20 cm will be automatically converted to 1.2 m (units follow the leftmost quantity).

      >>> a = EnergyArray([1, 2], "Ha")
      >>> b = EnergyArray([1, 2], "eV")
      >>> c = a + b
      >>> print(c)
      [ 1.03674933  2.07349865] Ha
      >>> c.to("eV")
      array([ 28.21138386,  56.42276772]) eV

  Override __new__.

  Error

    alias of `pymatgen.core.units.UnitError`

  property as_base_units

    Returns this ArrayWithUnit in base SI units, including derived units.

    Returns

      An ArrayWithUnit object in base SI units

  conversions()

    Returns a string showing the available conversions. Useful tool in interactive mode.

  property supported_units

    Supported units for specific unit type.

  to(new_unit)

    Conversion to a new_unit.

    Parameters

      new_unit – New unit type.

    Returns

      A ArrayWithFloatWithUnit object in the new units.

    Example usage: >>> e = EnergyArray([1, 1.1], “Ha”) >>> e.to(“eV”) array([ 27.21138386, 29.93252225]) eV

  property unit: str

    The unit, e.g., “eV”.

    Type

      return

  property unit_type: str

    The type of unit. Energy, Charge, etc.

    Type

      return

Charge = functools.partial(<class 'pymatgen.core.units.FloatWithUnit'>, unit_type='charge')

  A float with a charge unit.

  Parameters

    - val (float) – Value

    - unit (Unit) – E.g., C, e (electron charge). Must be valid unit or UnitError is raised.

Energy = functools.partial(<class 'pymatgen.core.units.FloatWithUnit'>, unit_type='energy')

  A float with an energy unit.

  Parameters

    - val (float) – Value

    - unit (Unit) – E.g., eV, kJ, etc. Must be valid unit or UnitError is raised.

class FloatWithUnit(val, unit, unit_type=None)

  Bases: `float`

  Subclasses float to attach a unit type. Typically, you should use the pre-defined unit type subclasses such as Energy, Length, etc. instead of using FloatWithUnit directly.

  Supports conversion, addition and subtraction of the same unit type. E.g., 1 m + 20 cm will be automatically converted to 1.2 m (units follow the leftmost quantity). Note that FloatWithUnit does not override the eq method for float, i.e., units are not checked when testing for equality. The reason is to allow this class to be used transparently wherever floats are expected.

      >>> e = Energy(1.1, "Ha")
      >>> a = Energy(1.1, "Ha")
      >>> b = Energy(3, "eV")
      >>> c = a + b
      >>> print(c)
      1.2102479761938871 Ha
      >>> c.to("eV")
      32.932522246000005 eV

  Initializes a float with unit.

  Parameters

    - val (float) – Value

    - unit (Unit) – A unit. E.g., “C”.

    - unit_type (str) – A type of unit. E.g., “charge”

  Error

    alias of `pymatgen.core.units.UnitError`

  property as_base_units

    Returns this FloatWithUnit in base SI units, including derived units.

    Returns

      A FloatWithUnit object in base SI units

  classmethod from_string(s)

    Initialize a FloatWithUnit from a string. Example Memory.from_string(“1. Mb”)

  property supported_units

    Supported units for specific unit type.

  to(new_unit)

    Conversion to a new_unit. Right now, only supports 1 to 1 mapping of units of each type.

    Parameters

      new_unit – New unit type.

    Returns

      A FloatWithUnit object in the new units.

    Example usage: >>> e = Energy(1.1, “eV”) >>> e = Energy(1.1, “Ha”) >>> e.to(“eV”) 29.932522246 eV

  property unit: str

    The unit, e.g., “eV”.

    Type

      return

  property unit_type: str

    The type of unit. Energy, Charge, etc.

    Type

      return

Length = functools.partial(<class 'pymatgen.core.units.FloatWithUnit'>, unit_type='length')

  A float with a length unit.

  Parameters

    - val (float) – Value

    - unit (Unit) – E.g., m, ang, bohr, etc. Must be valid unit or UnitError is raised.

Mass = functools.partial(<class 'pymatgen.core.units.FloatWithUnit'>, unit_type='mass')

  A float with a mass unit.

  Parameters

    - val (float) – Value

    - unit (Unit) – E.g., amu, kg, etc. Must be valid unit or UnitError is raised.

Memory = functools.partial(<class 'pymatgen.core.units.FloatWithUnit'>, unit_type='memory')

  A float with a memory unit.

  Parameters

    - val (float) – Value

    - unit (Unit) – E.g., Kb, Mb, Gb, Tb. Must be valid unit or UnitError is raised.

Temp = functools.partial(<class 'pymatgen.core.units.FloatWithUnit'>, unit_type='temperature')

  A float with a temperature unit.

  Parameters

    - val (float) – Value

    - unit (Unit) – E.g., K. Only K (kelvin) is supported.

Time = functools.partial(<class 'pymatgen.core.units.FloatWithUnit'>, unit_type='time')

  A float with a time unit.

  Parameters

    - val (float) – Value

    - unit (Unit) – E.g., s, min, h. Must be valid unit or UnitError is raised.

class Unit(unit_def)

  Bases: `collections.abc.Mapping`

  Represents a unit, e.g., “m” for meters, etc. Supports compound units. Only integer powers are supported for units.

  Constructs a unit.

  Parameters

    unit_def – A definition for the unit. Either a mapping of unit to powers, e.g., {“m”: 2, “s”: -1} represents “m^2 s^-1”, or simply as a string “kg m^2 s^-1”. Note that the supported format uses “^” as the power operator and all units must be space-separated.

  Error

    alias of `pymatgen.core.units.UnitError`

  property as_base_units

    Converts all units to base SI units, including derived units.

    Returns

      (base_units_dict, scaling factor). base_units_dict will not contain any constants, which are gathered in the scaling factor.

  get_conversion_factor(new_unit)

    Returns a conversion factor between this unit and a new unit. Compound units are supported, but must have the same powers in each unit type.

    Parameters

      new_unit – The new unit.

exception UnitError

  Bases: `BaseException`

  Exception class for unit errors.

kb = 8.617333262e-05

  Definitions of supported units. Values below are essentially scaling and conversion factors. What matters is the relative values, not the absolute. The SI units must have factor 1.

obj_with_unit(obj, unit)

  Returns a FloatWithUnit instance if obj is scalar, a dictionary of objects with units if obj is a dict, else an instance of ArrayWithFloatWithUnit.

  Parameters

    unit – Specific units (eV, Ha, m, ang, etc.).

unitized(unit)

  Useful decorator to assign units to the output of a function. You can also use it to standardize the output units of a function that already returns a FloatWithUnit or ArrayWithUnit. For sequences, all values in the sequences are assigned the same unit. It works with Python sequences only. The creation of numpy arrays loses all unit information. For mapping types, the values are assigned units.

  Parameters

    unit – Specific unit (eV, Ha, m, ang, etc.).

  Example usage:

      @unitized(unit="kg")
      def get_mass():
          return 123.45