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:
numpy.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__.
-
Error[source]¶ alias of
pymatgen.core.units.UnitError
-
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”
-
Error[source]¶ alias of
pymatgen.core.units.UnitError
-
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]¶ Initialize a FloatWithUnit from a string. 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:
collections.abc.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.
-
Error[source]¶ alias of
pymatgen.core.units.UnitError
-
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, unit)[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
unit – 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