.. _performance: Optimizing Performance ====================== Pint can impose a significant performance overhead on computationally-intensive problems. The following are some suggestions for getting the best performance. .. note:: Examples below are based on the IPython shell (which provides the handy %timeit extension), so they will not work in a standard Python interpreter. Use magnitudes when possible ---------------------------- It's significantly faster to perform mathematical operations on magnitudes (even though you're still using pint to retrieve them from a quantity object). .. ipython:: :verbatim: In [1]: from pint import UnitRegistry In [2]: ureg = UnitRegistry() In [3]: q1 = ureg('1m') In [5]: q2 = ureg('2m') In [6]: %timeit (q1 - q2) 8.24 us +- 44.5 ns per loop (mean +- std. dev. of 7 runs, 100,000 loops each) In [7]: %timeit (q1.magnitude - q2.magnitude) 214 ns +- 2.39 ns per loop (mean +- std. dev. of 7 runs, 1,000,000 loops each) This is especially important when using pint Quantities in conjunction with an iterative solver, such as the `brentq method`_ from scipy: .. ipython:: :verbatim: In [1]: from scipy.optimize import brentq In [2]: def foobar_with_quantity(x): ...: # find the value of x that equals q2 ...: ...: # assign x the same units as q2 ...: qx = ureg(str(x)+str(q2.units)) ...: ...: # compare the two quantities, then take their magnitude because ...: # brentq requires a dimensionless return type ...: return (qx - q2).magnitude In [3]: def foobar_with_magnitude(x): ...: # find the value of x that equals q2 ...: ...: # don't bother converting x to a quantity, just compare it with q2's magnitude ...: return x - q2.magnitude In [4]: %timeit brentq(foobar_with_quantity,0,q2.magnitude) 286 us +- 9.05 us per loop (mean +- std. dev. of 7 runs, 1,000 loops each) In [5]: %timeit brentq(foobar_with_magnitude,0,q2.magnitude) 1.14 us +- 21.3 ns per loop (mean +- std. dev. of 7 runs, 1,000,000 loops each) Bear in mind that altering computations like this **loses the benefits of automatic unit conversion**, so use with care. A safer method: wrapping ------------------------ A better way to use magnitudes is to use pint's wraps decorator (See :ref:`wrapping`). By decorating a function with wraps, you pass only the magnitude of an argument to the function body according to units you specify. As such this method is safer in that you are sure the magnitude is supplied in the correct units. .. ipython:: In [1]: import pint In [2]: ureg = pint.UnitRegistry() In [3]: import numpy as np In [4]: def f(x, y): ...: return (x - y) / (x + y) * np.log(x/y) In [5]: @ureg.wraps(None, ('meter', 'meter')) ...: def g(x, y): ...: return (x - y) / (x + y) * np.log(x/y) In [6]: a = 1 * ureg.meter In [7]: b = 1 * ureg.centimeter In [8]: %timeit f(a, b) 1000 loops, best of 3: 312 µs per loop In [9]: %timeit g(a, b) 10000 loops, best of 3: 65.4 µs per loop Speed up registry instantiation ------------------------------- When the registry is instantiated, the definition file is parsed, loaded and some pre-calculations are made to speed-up certain common operations. This process can be time consuming for a large definition file such as the default one (and very comprehensive) provided with pint. This can have a significant impact in command line applications that create and drop registries. Since version 0.19, part of this process can be cached resulting in a 5x to 20x performance improvement for registry instantiation using an included version of flexcache_. This feature is experimental and therefore disabled by default, but might be enable in future versions. To enable this feature just use the `cache_folder` argument to provide (as a str or pathlib.Path) the location where the cache will be saved. .. code-block:: python >>> import pint >>> ureg = pint.UnitRegistry(cache_folder="/my/cache/folder") # doctest: +SKIP If you want to use the default cache folder provided by the OS, use **:auto:** .. code-block:: python >>> import pint >>> ureg = pint.UnitRegistry(cache_folder=":auto:") # doctest: +SKIP Pint use an included version of appdirs_ to obtain the correct folder, for example in macOS is `/Users//Library/Caches/pint` In any case, you can check the location of the cache folder. .. code-block:: python >>> ureg.cache_folder # doctest: +SKIP .. note:: Cached files are stored in pickle format with a unique name generated from hashing the path of the original definition file. This hash also includes the platform (e.g. 'Linux'), python implementation (e.g. ‘CPython'), python version, pint version and the `non_int_type` setting of the UnitRegistry to avoid mixing incompatible caches. If the definition file includes another (using the `@import` directive), this latter file will be cached independently. Finally, when a definition file is loaded upon registry instantiation the RegistryCache is also cached. The cache is invalidated based on the content hash. Therefore, if you modify the text definition file a new cache file will be generated. Caching by content hash allows sharing the same cache across multiple environments that use the same python and pint versions. At any moment, you can delete the cache folder without any risk. .. _`brentq method`: http://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.brentq.html .. _appdirs: https://pypi.org/project/appdirs/ .. _flexcache: https://github.com/hgrecco/flexcache/