pyunitwizard.api package#

Submodules#

pyunitwizard.api.comparison module#

Comparison helpers for quantities and units.

pyunitwizard.api.comparison.are_close(quantity_1, quantity_2, rtol=1e-05, atol=1e-08)[source]#

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.api.comparison.are_compatible(quantity_or_unit_1, quantity_or_unit_2)[source]#

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.api.comparison.are_equal(quantity_or_unit_1, quantity_or_unit_2, same_form=False)[source]#

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.api.comparison.compatibility(quantity_or_unit_1, quantity_or_unit_2)[source]#

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.api.comparison.similarity(quantity_or_unit_1, quantity_or_unit_2, relative_tolerance=1e-08)[source]#

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.api.construction module#

Factory helpers for creating quantities and units.

pyunitwizard.api.construction.quantity(value, unit=None, form=None, parser=None, standardized=False)[source]#

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.api.construction.unit(unit, form=None, parser=None)[source]#

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

pyunitwizard.api.context module#

Context manager for temporary PyUnitWizard configuration.

pyunitwizard.api.context.context(default_form=None, default_parser=None, standard_units=None)[source]#

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.api.conversion module#

Conversion helpers bridging between different quantity backends.

pyunitwizard.api.conversion.convert(quantity_or_unit, to_unit=None, to_form=None, parser=None, to_type='quantity')[source]#

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.api.conversion.to_string(quantity_or_unit, to_unit=None, parser=None)[source]#

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.api.extraction module#

Value and unit extraction helpers.

pyunitwizard.api.extraction.change_value(quantity, value)[source]#

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.api.extraction.get_unit(quantity, to_form=None, parser=None, standardized=False)[source]#

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.api.extraction.get_value(quantity, to_unit=None, parser=None, standardized=False)[source]#

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.api.extraction.get_value_and_unit(quantity, to_unit=None, to_form=None, parser=None, standardized=False)[source]#

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.api.introspection module#

Introspection helpers for PyUnitWizard quantities and units.

pyunitwizard.api.introspection.get_dimensionality(quantity_or_unit)[source]#

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.api.introspection.get_form(quantity_or_unit)[source]#

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.api.introspection.is_dimensionless(quantity_or_unit)[source]#

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.api.introspection.is_quantity(quantity_or_unit, parser=None)[source]#

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.api.introspection.is_unit(quantity_or_unit, parser=None)[source]#

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.api.standardization module#

Standardization helpers for canonical units.

pyunitwizard.api.standardization.get_standard_units(quantity_or_unit=None, dimensionality=None, form=None, parser=None)[source]#

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.api.standardization.standardize(quantity_or_unit, to_form=None)[source]#

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.api.validation module#

Validation helpers for PyUnitWizard.

pyunitwizard.api.validation.check(quantity_or_unit, dimensionality=None, value_type=None, shape=None, unit=None, dtype_name=None)[source]#

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

Module contents#

Public API groupings for PyUnitWizard.

pyunitwizard.api.are_close(quantity_1, quantity_2, rtol=1e-05, atol=1e-08)[source]#

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.api.are_compatible(quantity_or_unit_1, quantity_or_unit_2)[source]#

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.api.are_equal(quantity_or_unit_1, quantity_or_unit_2, same_form=False)[source]#

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.api.change_value(quantity, value)[source]#

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.api.check(quantity_or_unit, dimensionality=None, value_type=None, shape=None, unit=None, dtype_name=None)[source]#

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.api.compatibility(quantity_or_unit_1, quantity_or_unit_2)[source]#

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.api.context(default_form=None, default_parser=None, standard_units=None)[source]#

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.api.convert(quantity_or_unit, to_unit=None, to_form=None, parser=None, to_type='quantity')[source]#

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.api.get_dimensionality(quantity_or_unit)[source]#

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.api.get_form(quantity_or_unit)[source]#

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.api.get_standard_units(quantity_or_unit=None, dimensionality=None, form=None, parser=None)[source]#

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.api.get_unit(quantity, to_form=None, parser=None, standardized=False)[source]#

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.api.get_value(quantity, to_unit=None, parser=None, standardized=False)[source]#

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.api.get_value_and_unit(quantity, to_unit=None, to_form=None, parser=None, standardized=False)[source]#

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.api.is_dimensionless(quantity_or_unit)[source]#

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.api.is_quantity(quantity_or_unit, parser=None)[source]#

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.api.is_unit(quantity_or_unit, parser=None)[source]#

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.api.quantity(value, unit=None, form=None, parser=None, standardized=False)[source]#

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.api.similarity(quantity_or_unit_1, quantity_or_unit_2, relative_tolerance=1e-08)[source]#

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.api.standardize(quantity_or_unit, to_form=None)[source]#

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.api.to_string(quantity_or_unit, to_unit=None, parser=None)[source]#

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.api.unit(unit, form=None, parser=None)[source]#

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