pyiron_base.utils.units module

class pyiron_base.utils.units.PyironUnitRegistry

Bases: object

Module to record units for physical quantities within pyiron. This module is used for defining the units for different pyiron submodules.

Useage:

>>> import pint
>>> from pyiron_base.utils.units import PyironUnitRegistry
>>> pint_registry = pint.UnitRegistry()

After instantiating, the pint units for different physical quantities can be registered as follows

>>> base_registry = PyironUnitRegistry()
>>> base_registry.add_quantity(quantity="energy", unit=pint_registry.eV, data_type=float)

Labels corresponding to a particular physical quantity can also be registered

>>> base_registry.add_labels(labels=["energy_tot", "energy_pot"], quantity="energy")

For more information on working with pint, see: https://pint.readthedocs.io/en/0.10.1/tutorial.html

add_labels(labels, quantity)

Maps quantities with different labels to quantities already defined in the registry

Parameters:

labels (list/ndarray) – List of labels
quantity (str) – Physical quantity associated with the labels

Raises:

KeyError – If quantity is not yet added with :method:`.add_quantity()`

Note: quantity should already be a key of unit_dict

add_quantity(quantity, unit, data_type=<class 'float'>)

Add a quantity to a registry

Parameters:

quantity (str) – The physical quantity
unit (pint.unit.Unit/pint.quantity.Quantity) – pint unit or quantity
data_type (type) – Data type in which the quantity has to be stored

property dtype_dict

A dictionary of the names of the different physical quantities to the corresponding datatype in which they are to be stored

Returns:: dict

get_dtype(quantity)

Returns the data type in which the quantity will be stored

Parameters:: quantity (str) – The quantity
Returns:: Corresponding data type
Return type:: type
Raises:: KeyError – If quantity is not yet added with :method:`.add_quantity()` or :method:`.add_labels()`

property quantity_dict

A dictionary of the different labels stored and the physical quantity they correspond to

Returns:: dict

property unit_dict

A dictionary of the different physical quantities and the corresponding pint unit

Returns:: dict

class pyiron_base.utils.units.UnitConverter(base_registry, code_registry)

Bases: object

Module to handle conversions between two different unit registries mainly use to convert units between codes and pyiron submodules.

To instantiate this class, you need two units registries: a base units registry and a code registry:

>>> import pint
>>> pint_registry = pint.UnitRegistry()
>>> base = PyironUnitRegistry()
>>> base.add_quantity(quantity="energy", unit=pint_registry.eV)
>>> code = PyironUnitRegistry()
>>> code.add_quantity(quantity="energy",
...                         unit=pint_registry.kilocal / (pint_registry.mol * pint_registry.N_A))
>>> unit_converter = UnitConverter(base_registry=base, code_registry=code)

The unit converter instance can then be used to obtain conversion factors between code and base units either as a pint quantity:

>>> print(unit_converter.code_to_base_pint("energy"))
0.04336410424180094 electron_volt

or as a scalar:

>>> print(unit_converter.code_to_base_value("energy"))
0.04336410424180094

Alternatively, the unit converter can also be used as decorators for functions that return an array scaled into appropriate units:

>>> @unit_converter.code_to_base(quantity="energy")
... def return_ones():
...    return np.ones(5)
>>> print(return_ones())
[0.0433641 0.0433641 0.0433641 0.0433641 0.0433641]

The decorator can also be used to assign units for numpy arrays (for more info see https://pint.readthedocs.io/en/0.10.1/numpy.html)

>>> @unit_converter.base_units(quantity="energy")
... def return_ones_ev():
...     return np.ones(5)
>>> print(return_ones_ev())
[1.0 1.0 1.0 1.0 1.0] electron_volt

base_to_code(quantity)

Decorator for functions that returns a numpy array. Multiples the function output by the base to code units conversion factor

Parameters:: quantity (str) – Name of the quantity
Returns:: Decorated function
Return type:: function

base_to_code_pint(quantity)

Get the conversion factor as a pint quantity from base to code units

Parameters:: quantity (str) – Name of quantity
Returns:: Conversion factor as a pint quantity
Return type:: pint.quantity.Quantity

base_to_code_value(quantity)

Get the conversion factor as a scalar from base to code units

Parameters:: quantity (str) – Name of quantity
Returns:: Conversion factor as a float
Return type:: float

base_units(quantity)

Decorator for functions that returns a numpy array. Assigns the base unit of the quantity to the function output

Parameters:: quantity (str) – Name of the quantity
Returns:: Decorated function
Return type:: function

code_to_base(quantity)

Decorator for functions that returns a numpy array. Multiples the function output by the code to base units conversion factor

Parameters:: quantity (str) – Name of the quantity
Returns:: Decorated function
Return type:: function

code_to_base_pint(quantity)

Get the conversion factor as a pint quantity from code to base units

Parameters:: quantity (str) – Name of quantity
Returns:: Conversion factor as a pint quantity
Return type:: pint.quantity.Quantity

code_to_base_value(quantity)

Get the conversion factor as a scalar from code to base units

Parameters:: quantity (str) – Name of quantity
Returns:: Conversion factor as a float
Return type:: float

code_units(quantity)

Decorator for functions that returns a numpy array. Assigns the code unit of the quantity to the function output

Parameters:: quantity (str) – Name of the quantity
Returns:: Decorated function
Return type:: function