pyiron_base.utils.units.UnitConverter

class pyiron_base.utils.units.UnitConverter(base_registry: PyironUnitRegistry, code_registry: PyironUnitRegistry)

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.043364104241800934 electron_volt

or as a scalar:

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

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

__init__(base_registry: PyironUnitRegistry, code_registry: PyironUnitRegistry)

Parameters:

• base_registry (PyironUnitRegistry) – Base unit registry

• code_registry (PyironUnitRegistry) – Code specific unit registry

Methods

__init__(base_registry, code_registry)	param base_registry: Base unit registry
base_to_code(quantity)	Decorator for functions that returns a numpy array.
base_to_code_pint(quantity)	Get the conversion factor as a pint quantity from base to code units
base_to_code_value(quantity)	Get the conversion factor as a scalar from base to code units
base_units(quantity)	Decorator for functions that returns a numpy array.
code_to_base(quantity)	Decorator for functions that returns a numpy array.
code_to_base_pint(quantity)	Get the conversion factor as a pint quantity from code to base units
code_to_base_value(quantity)	Get the conversion factor as a scalar from code to base units
code_units(quantity)	Decorator for functions that returns a numpy array.

base_to_code(quantity: str) → callable

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: str) → 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

base_to_code_value(quantity: str) → float

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: str) → callable

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: str) → callable

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: str) → 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

code_to_base_value(quantity: str) → float

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: str) → callable

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