Converting Units

pyEQL uses pint to automatically interpret and convert units. For this reason, many quantitative arguments are passed to functions as strings rather than numbers. For example, to specify temperature, you pass temperature='298 K' and NOT temperature=298.

Quantity objects

Most Solution class methods return pint Quantity objects.

>>> from pyEQL import Solution
>>> s = Solution()
>>> s.pressure
<Quantity(1, 'standard_atmosphere')>

If you want to create a simple Quantity not attached to a Solution, you can do so as follows:

>>> from pyEQL import ureg
>>> q = ureg.Quantity('1 m')

Quantity objects have three important attributes: magnitude, units, and dimensionality. To get the numerical value, call magnitude

>>> from pyEQL import ureg
>>> q = ureg.Quantity('1 m')
>>> q.magnitude
1

Similarly, to get the units, call units

>>> from pyEQL import ureg
>>> q = ureg.Quantity('1 m')
>>> q.units
<Unit('meter')>

To convert from one unit to another, use to():

>>> from pyEQL import ureg
>>> q = ureg.Quantity('1 m')
>>> q.to('ft')
<Quantity(3.2808399, 'foot')>

If you encounter a DimensionalityError when working with pyEQL, it probably means you are trying to do an operation on two quantities with incompatible units (or perhaps on a Quantity and a regular float or int). For example, you can’t convert m into m**3:

>>> from pyEQL import ureg
>>> q = ureg.Quantity('1 m')
>>> q.to('m^3')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/ryan/mambaforge/envs/pbx/lib/python3.10/site-packages/pint/facets/plain/quantity.py", line 517, in to
    magnitude = self._convert_magnitude_not_inplace(other, *contexts, **ctx_kwargs)
  File "/home/ryan/mambaforge/envs/pbx/lib/python3.10/site-packages/pint/facets/plain/quantity.py", line 462, in _convert_magnitude_not_inplace
    return self._REGISTRY.convert(self._magnitude, self._units, other)
  File "/home/ryan/mambaforge/envs/pbx/lib/python3.10/site-packages/pint/facets/plain/registry.py", line 961, in convert
    return self._convert(value, src, dst, inplace)
  File "/home/ryan/mambaforge/envs/pbx/lib/python3.10/site-packages/pint/facets/context/registry.py", line 403, in _convert
    return super()._convert(value, src, dst, inplace)
  File "/home/ryan/mambaforge/envs/pbx/lib/python3.10/site-packages/pint/facets/nonmultiplicative/registry.py", line 254, in _convert
    return super()._convert(value, src, dst, inplace)
  File "/home/ryan/mambaforge/envs/pbx/lib/python3.10/site-packages/pint/facets/plain/registry.py", line 1000, in _convert
    raise DimensionalityError(src, dst, src_dim, dst_dim)
pint.errors.DimensionalityError: Cannot convert from 'meter' ([length]) to 'meter ** 3' ([length] ** 3)

Refer to the pint documentation for more etails about working with Quantity.

Note

Note that the meaning of ureg is equivalent in the above pyEQL examples and in the pint documentation. pyEQL instantiates its own UnitRegistry (with custom definitions for solution chemistry) and assigns it to the variable ureg. In most pint examples, the line ureq = UnitRegistry() does the same thing.

Important

if you use pyEQL in conjunction with another module that also uses pint for units-aware calculations, you must convert all Quantity objects to strings before passing them to the other module, as pint cannot perform mathematical operations on units that belong to different “registries.” See the pint documentation for more details.

Custom Units

pyEQL extends the pint unit library to include some additional units that are commonly encountered in solution chemistry.