pymatgen.core.units module

class ArrayWithUnit

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

Error

alias of UnitError

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.

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

unit

unit_type

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 UnitError

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”)

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

unit

unit_type

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 UnitError

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.

bohr_to_ang = 0.52917721067

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.

check_mappings(u)

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