pyunitwizard package

Subpackages

• pyunitwizard.api package
  • Submodules
  • pyunitwizard.api.comparison module
    • are_close()
    • are_compatible()
    • are_equal()
    • compatibility()
    • similarity()
  • pyunitwizard.api.construction module
    • quantity()
    • unit()
  • pyunitwizard.api.context module
    • context()
  • pyunitwizard.api.conversion module
    • convert()
    • to_string()
  • pyunitwizard.api.extraction module
    • change_value()
    • get_unit()
    • get_value()
    • get_value_and_unit()
  • pyunitwizard.api.introspection module
    • get_dimensionality()
    • get_form()
    • is_dimensionless()
    • is_quantity()
    • is_unit()
  • pyunitwizard.api.standardization module
    • get_standard_units()
    • standardize()
  • pyunitwizard.api.validation module
    • check()
  • Module contents
    • are_close()
    • are_compatible()
    • are_equal()
    • change_value()
    • check()
    • compatibility()
    • context()
    • convert()
    • get_dimensionality()
    • get_form()
    • get_standard_units()
    • get_unit()
    • get_value()
    • get_value_and_unit()
    • is_dimensionless()
    • is_quantity()
    • is_unit()
    • quantity()
    • similarity()
    • standardize()
    • to_string()
    • unit()
• pyunitwizard.configure package
  • Submodules
  • pyunitwizard.configure.configure module
    • add_constant()
    • get_default_form()
    • get_default_parser()
    • get_libraries_loaded()
    • get_libraries_supported()
    • get_parsers_loaded()
    • get_parsers_supported()
    • get_standard_units()
    • load_library()
    • reset()
    • resolve_config_module()
    • set_default_form()
    • set_default_parser()
    • set_standard_units()
  • Module contents
• pyunitwizard.constants package
  • Submodules
  • pyunitwizard.constants.constants module
    • get_constant()
    • show_constants()
  • Module contents
• pyunitwizard.forms package
  • Submodules
  • pyunitwizard.forms.api_astropy_unit module
    • change_value()
    • compatibility()
    • convert()
    • dimensionality()
    • get_unit()
    • get_value()
    • is_form()
    • is_quantity()
    • is_unit()
    • make_quantity()
    • quantity_to_openmm_unit()
    • quantity_to_pint()
    • quantity_to_string()
    • quantity_to_unyt()
    • string_to_quantity()
    • string_to_unit()
    • unit_to_openmm_unit()
    • unit_to_pint()
    • unit_to_string()
    • unit_to_unyt()
  • pyunitwizard.forms.api_openmm_unit module
    • change_value()
    • compatibility()
    • convert()
    • dimensionality()
    • get_unit()
    • get_value()
    • is_form()
    • is_quantity()
    • is_unit()
    • make_quantity()
    • quantity_to_astropy_units()
    • quantity_to_pint()
    • quantity_to_string()
    • quantity_to_unyt()
    • string_to_quantity()
    • string_to_unit()
    • unit_to_astropy_units()
    • unit_to_pint()
    • unit_to_string()
    • unit_to_unyt()
  • pyunitwizard.forms.api_physipy module
  • pyunitwizard.forms.api_pint module
    • change_value()
    • compatibility()
    • convert()
    • dimensionality()
    • get_unit()
    • get_value()
    • is_form()
    • is_quantity()
    • is_unit()
    • make_quantity()
    • quantity_to_astropy_units()
    • quantity_to_openmm_unit()
    • quantity_to_physipy()
    • quantity_to_quantities()
    • quantity_to_string()
    • quantity_to_unyt()
    • string_to_quantity()
    • string_to_unit()
    • unit_to_astropy_units()
    • unit_to_openmm_unit()
    • unit_to_physipy()
    • unit_to_quantities()
    • unit_to_string()
    • unit_to_unyt()
  • pyunitwizard.forms.api_quantities module
  • pyunitwizard.forms.api_string module
    • change_value()
    • compatibility()
    • convert()
    • dimensionality()
    • get_unit()
    • get_value()
    • is_form()
    • is_quantity()
    • is_unit()
    • make_quantity()
    • quantity_to_astropy_units()
    • quantity_to_openmm_unit()
    • quantity_to_physipy()
    • quantity_to_pint()
    • quantity_to_quantities()
    • quantity_to_unyt()
    • unit_to_astropy_units()
    • unit_to_openmm_unit()
    • unit_to_physipy()
    • unit_to_pint()
    • unit_to_quantities()
    • unit_to_unyt()
  • pyunitwizard.forms.api_unyt module
    • change_value()
    • compatibility()
    • convert()
    • dimensionality()
    • get_unit()
    • get_value()
    • is_form()
    • is_quantity()
    • is_unit()
    • make_quantity()
    • quantity_to_astropy_units()
    • quantity_to_openmm_unit()
    • quantity_to_pint()
    • quantity_to_string()
    • string_to_quantity()
    • string_to_unit()
    • unit_to_astropy_units()
    • unit_to_openmm_unit()
    • unit_to_pint()
    • unit_to_string()
  • pyunitwizard.forms.template_api_form module
    • compatibility()
    • convert()
    • dimensionality()
    • get_unit()
    • get_value()
    • is_quantity()
    • is_unit()
    • make_quantity()
    • string_to_quantity()
    • to_string()
  • Module contents
    • load_library()
• pyunitwizard.utils package
  • Subpackages
    • pyunitwizard.utils.matplotlib package
      • Module contents
    • pyunitwizard.utils.numpy package
      • Submodules
      • pyunitwizard.utils.numpy.column_stack module
      • pyunitwizard.utils.numpy.hstack module
      • pyunitwizard.utils.numpy.ops module
      • pyunitwizard.utils.numpy.repeat module
      • pyunitwizard.utils.numpy.stack module
      • pyunitwizard.utils.numpy.vstack module
      • Module contents
    • pyunitwizard.utils.pandas package
      • Module contents
    • pyunitwizard.utils.plot package
      • Module contents
    • pyunitwizard.utils.sequences package
      • Submodules
      • pyunitwizard.utils.sequences.concatenate module
      • pyunitwizard.utils.sequences.is_quantity_value_sequence module
      • pyunitwizard.utils.sequences.is_sequence module
      • pyunitwizard.utils.sequences.slice module
      • Module contents
  • Module contents

Submodules

pyunitwizard.kernel module

pyunitwizard.kernel.initialize()

Initialize global runtime state containers.

Returns:

Global runtime variables are reset in place.

Return type:

None

Examples

>>> import pyunitwizard.kernel as kernel
>>> kernel.initialize()

pyunitwizard.parse module

pyunitwizard.parse.parse(string, parser=None, to_form=None)

Parses a string and returns a quantity.

Parameters:

• string (str) – A string quantity.

• parser (str) – The parser that will be used.

• str (to_form;) – The form of the quantity. Can be “pint”, “openmm.unit”, “unyt”, “astropy.units” or “string”.

• optional – The form of the quantity. Can be “pint”, “openmm.unit”, “unyt”, “astropy.units” or “string”.

• to_form (str | None)

Returns:

A quantity.

Return type:

QuantityLike

Module contents

PyUnitWizard Quantities and units assistant.

pyunitwizard.are_close(quantity_1, quantity_2, rtol=1e-05, atol=1e-08)

Compares whether two quantities are similiar within a specified tolerance.

Parameters:

• quantity_or_unit_1 (QuantityOrUnit) – A quantity or a unit

• quantity_or_unit_2 (QuantityOrUnit) – A quantity or a unit

• relative_tolerance (float) – The relative tolerance to compare the quantities.

• quantity_1 (QuantityLike)

• quantity_2 (QuantityLike)

• rtol (float)

• atol (float)

Returns:

Whether the quantities or units are similar.

Return type:

bool

pyunitwizard.are_compatible(quantity_or_unit_1, quantity_or_unit_2)

Check whether two quantities or units are compatible. This means that they have the same dimensionalities.

Parameters:

• quantity_or_unit_1 (QuantityOrUnit) – A quantity or a unit

• quantity_or_unit_2 (QuantityOrUnit) – A quantity or a unit

Returns:

Whether the quantities or units are compatible.

Return type:

bool

pyunitwizard.are_equal(quantity_or_unit_1, quantity_or_unit_2, same_form=False)

Compares whether two quantities are similiar within a specified tolerance.

Parameters:

• quantity_or_unit_1 (QuantityOrUnit) – A quantity or a unit

• quantity_or_unit_2 (QuantityOrUnit) – A quantity or a unit

• relative_tolerance (float) – The relative tolerance to compare the quantities.

• same_form (bool)

Returns:

Whether the quantities or units are similar.

Return type:

bool

pyunitwizard.change_value(quantity, value)

Return a quantity with a replaced value while preserving unit and form.

Parameters:

• quantity (QuantityLike) – Input quantity.

• value (numpy.ndarray or float or int) – New numeric value to assign.

Returns:

Quantity with updated value and original unit.

Return type:

QuantityLike

Examples

>>> import pyunitwizard as puw
>>> q = puw.quantity(1.0, "nanometer")
>>> puw.change_value(q, 2.0)

pyunitwizard.check(quantity_or_unit, dimensionality=None, value_type=None, shape=None, unit=None, dtype_name=None)

Check if a quantity or unit has the specified dimensionality, value_type, shape, unit or data type.

Parameters:

• quantity_or_unit (Any) – A quantity or unit object. If any other object is passed False will be returned.

• dimensionality (dict) – A dictionary specifying the dimensionality of the quantity or unit.

• value_type (Any) – The type of the quantity. Can be int, float, np.ndarray.

• shape (tuple of int) – For non scalar quantities. A tuple with the shape of the array.

• unit (str) – Name of the unit.

• dtype_name (str) – For non scalar quantities. The dtype of the array (i.e float64).

Returns:

True if the quantity or unit has the specified parameters.

Return type:

bool

pyunitwizard.compatibility(quantity_or_unit_1, quantity_or_unit_2)

Check whether two quantities or units are dimensionally compatible.

Parameters:

• quantity_or_unit_1 (QuantityOrUnit) – First quantity or unit.

• quantity_or_unit_2 (QuantityOrUnit) – Second quantity or unit.

Returns:

True when both inputs are compatible for conversion/comparison.

Return type:

bool

Examples

>>> import pyunitwizard as puw
>>> puw.compatibility("1 nm", "10 angstrom")

pyunitwizard.context(default_form=None, default_parser=None, standard_units=None)

Context manager to temporarily change PyUnitWizard configuration.

Parameters:

• default_form (str, optional) – Temporary default form.

• default_parser (str, optional) – Temporary default parser.

• standard_units (list of str, optional) – Temporary standard units.

Examples

>>> with puw.context(default_form='pint', standard_units=['nm', 'ps']):
>>>     q = puw.standardize(input_q)

pyunitwizard.convert(quantity_or_unit, to_unit=None, to_form=None, parser=None, to_type='quantity')

Convert a quantity or unit across unit systems, forms, and output types.

Parameters:

• quantity_or_unit (Any) – Input quantity or unit to convert. It can be any supported runtime form, including strings when a compatible parser is configured.

• to_unit (str, optional) – Target unit. When provided, the quantity is converted to this unit before returning.

• to_form ({"unyt", "pint", "openmm.unit", "astropy.units", "string"}, optional) – Target backend form. If omitted, the input form is preserved.

• parser ({"pint", "openmm.unit", "astropy.units"}, optional) – Parser used when quantity_or_unit or to_unit is provided as a string.

• to_type ({"quantity", "unit", "value"}, optional, default="quantity") – Output type to return.

Returns:

Converted object in the requested unit/form/type.

Return type:

QuantityOrUnit or float or numpy.ndarray

Raises:

BadCallError – If to_type is not one of "quantity", "unit", or "value".

Examples

>>> import pyunitwizard as puw
>>> q = puw.quantity(1.0, "nanometer")
>>> puw.convert(q, to_unit="angstrom")

pyunitwizard.get_dimensionality(quantity_or_unit)

Return dimensional exponents for a quantity or unit.

Parameters:

quantity_or_unit (QuantityOrUnit) – Quantity or unit to inspect. String values are parsed when possible.

Returns:

Mapping of fundamental dimensions to integer exponents.

Return type:

dict

Raises:

NotImplementedFormError – If the input form is not supported by current runtime adapters.

Examples

>>> import pyunitwizard as puw
>>> puw.get_dimensionality("1 nanometer")

pyunitwizard.get_form(quantity_or_unit)

Returns the form of a quantity as a string.

Parameters:

quantity_or_unit (QuantityOrUnit) – A quanitity or a unit

Returns:

The form of the quantity

Return type:

{“string”, “pint”, “openmm.unit”, “unyt”}

pyunitwizard.get_standard_units(quantity_or_unit=None, dimensionality=None, form=None, parser=None)

Returns standard unit of the quantity or unit passed.

Parameters:

• quantity_or_unit (Any) – A quantity or unit

• dimensionality (dict | None)

• form (str | None)

• parser (str | None)

Returns:

The standard unit.

Return type:

str

Raises:

NoStandardsError – If no standard units were defined.

pyunitwizard.get_unit(quantity, to_form=None, parser=None, standardized=False)

Returns the unit of a quantity.

Parameters:

• to_unit (str, optional) –

  Name of the unit to which the quantity will be converted (i.e kcal/mol).

  form{“unyt”, “pint”, “openmm.unit”, “astropy.units”, “string”}, optional

  If passed the unit will be converted to that form. This is the type that will be returned

• parser ({"unyt", "pint", "openmm.unit", "astropy.units"}, optional) – The parser to use.

• quantity (QuantityLike)

• to_form (str | None)

• standardized (bool | None)

Returns:

The unit.

Return type:

UnitLike

pyunitwizard.get_value(quantity, to_unit=None, parser=None, standardized=False)

Returns the value of a quantity.

Parameters:

• to_unit (str, optional) – Name of the unit to which the quantity will be converted (i.e kcal/mol).

• parser ({"unyt", "pint", "openmm.unit", "astropy.units"}, optional) – The parser to use.

• quantity (QuantityLike)

• standardized (bool | None)

Returns:

An array with the quantity value or a a float or an int if it’s a scalar.

Return type:

np.ndarray or float or int

pyunitwizard.get_value_and_unit(quantity, to_unit=None, to_form=None, parser=None, standardized=False)

Returns the value and unit of a quantity.

Parameters:

• to_unit (str, optional) – Name of the unit to which the quantity will be converted (i.e kcal/mol).

• parser ({"unyt", "pint", "openmm.unit", "astropy.units"}, optional) – The parser to use.

• quantity (QuantityLike)

• to_form (str | None)

• standardized (bool | None)

Returns:

• np.ndarray or float or int

• UnitLike – The value and unit of the input quantity.

Return type:

Tuple[ndarray | float | int, UnitLike]

pyunitwizard.is_dimensionless(quantity_or_unit)

Check wheter a quantity or unit is dimensionless.

Parameters:

quantity_or_unit (QuantityOrUnit) – A quantity or a unit

Returns:

Whether the quantity or unit is dimensionless.

Return type:

bool

pyunitwizard.is_quantity(quantity_or_unit, parser=None)

Check whether an object is a quantity

Parameters:

• quantity_or_unit (QuantityOrUnit) – A quanitity or a unit

• parser ({"unyt", "pint", "openmm.unit", "astropy.units"}, optional) – The parser for string quantities

Returns:

False if it’s not a quantity

Return type:

bool

pyunitwizard.is_unit(quantity_or_unit, parser=None)

Check whether an object is a unit

Parameters:

• quantity_or_unit (QuantityOrUnit) – A quantity or a unit

• parser ({"unyt", "pint", "openmm.unit", "astropy.units"}, optional) – The parser for string quantities

Returns:

False if it’s not a unit

Return type:

bool

pyunitwizard.quantity(value, unit=None, form=None, parser=None, standardized=False)

Returns a quantity.

Parameters:

• value (int, float or arraylike) – The value of the quantity. Can be a scalar or an array like type.

• unit (UnitLike) – Unit in of the quantity in any of the accepted form.

• form ({"unyt", "pint", "openmm.unit", "astropy.units", "string"}, optional) – Output form of the quantity.

• parser ({"unyt", "pint", "openmm.unit", "astropy.units"}, optional) – The parser to use.

• standardized (bool, optional) – Return a standardized quantity, default=False.

Returns:

The quantity.

Return type:

QuantityLike

pyunitwizard.similarity(quantity_or_unit_1, quantity_or_unit_2, relative_tolerance=1e-08)

Compare two quantities using relative tolerance semantics.

Parameters:

• quantity_or_unit_1 (QuantityOrUnit) – First quantity or unit to compare.

• quantity_or_unit_2 (QuantityOrUnit) – Second quantity or unit to compare.

• relative_tolerance (float, default=1e-8) – Relative tolerance used internally as rtol in are_close().

Returns:

True when values are close within tolerance and units are compatible.

Return type:

bool

Examples

>>> import pyunitwizard as puw
>>> a = puw.quantity(1.0, "nanometer")
>>> b = puw.quantity(10.0, "angstrom")
>>> puw.similarity(a, b)

pyunitwizard.standardize(quantity_or_unit, to_form=None)

Concert a quantity or unit to standard units.

Parameters:

• quantity_or_unit (QuantityOrUnit) – The quantity or a unit that will be converted.

• to_form (str, optional.) – The form to transform to

Returns:

The quantity ot unit converted to standard units.

Return type:

QuantityOrUnit

Raises:

NoStandardsError – If no standard units were defined.

pyunitwizard.to_string(quantity_or_unit, to_unit=None, parser=None)

Return a quantity or unit converted to string form.

Parameters:

• quantity_or_unit (Any) – Input quantity or unit to convert.

• to_unit (str, optional) – Target unit expressed as string.

• parser ({"pint", "openmm.unit", "astropy.units"}, optional) – Parser used when string inputs require explicit parsing.

Returns:

Quantity or unit represented in string form.

Return type:

str

Examples

>>> import pyunitwizard as puw
>>> q = puw.quantity(1.0, "nanometer")
>>> puw.to_string(q, to_unit="angstrom")

pyunitwizard.unit(unit, form=None, parser=None)

Returns a unit.

Parameters:

• unit (str) – Name of the unit (i.e kcal/mol).

• form ({"unyt", "pint", "openmm.unit", "astropy.units", "string"}, optional) – The form of the unit. This is the type that will be returned

• parser ({"unyt", "pint", "openmm.unit", "astropy.units"}, optional) – The parser to use.

Returns:

The unit.

Return type:

Unitlike