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.