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)[source]
Bases:
ndarraySubclasses 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__.
- property as_base_units[source]
Returns this ArrayWithUnit in base SI units, including derived units.
- Returns:
An ArrayWithUnit object in base SI units
- conversions()[source]
Returns a string showing the available conversions. Useful tool in interactive mode.
- Charge = functools.partial(<class 'pymatgen.core.units.FloatWithUnit'>, unit_type='charge')[source]
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')[source]
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)[source]
Bases:
floatSubclasses 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”
- property as_base_units[source]
Returns this FloatWithUnit in base SI units, including derived units.
- Returns:
A FloatWithUnit object in base SI units
- classmethod from_string(s)[source]
Parse string to FloatWithUnit.
Example: Memory.from_string(“1. Mb”)
- Length = functools.partial(<class 'pymatgen.core.units.FloatWithUnit'>, unit_type='length')[source]
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')[source]
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')[source]
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')[source]
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')[source]
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)[source]
Bases:
MappingRepresents 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.
- kb = 8.617333262e-05[source]
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: Any, unit: str) FloatWithUnit | ArrayWithUnit | dict[str, FloatWithUnit | ArrayWithUnit][source]
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:
obj (Any) – Object to be given a unit.
unit (str) – Specific units (eV, Ha, m, ang, etc.).
- unitized(unit)[source]
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