Pint

https://pint.readthedocs.io/en/stable/
Admin
Pint is a Python library that makes handling units and unit conversions easy, enabling developers to...
Tokens:126,880
Snippets:1,075
Trust Score:8.3
Update:1 month ago
Show doc for...
Tokens:
Raw
### Set up environment with venv/pip on Linux or OSX

Source: https://pint.readthedocs.io/en/stable/dev/contributing.html

Manual setup instructions for creating a virtual environment and installing dependencies.

```bash
$ git clone git@github.com:hgrecco/pint.git
$ cd pint
$ python -m virtualenv venv
$ source venv/bin/activate
$ pip install -e '.[test]'
$ pip install -r requirements_docs.txt
$ pip install pre-commit # This step and the next are optional but recommended.
$ pre-commit install
```

--------------------------------

### Install Pint using pip

Source: https://pint.readthedocs.io/en/stable/_sources/getting/index.rst

Use this command to install Pint if you prefer using pip. Ensure Python 3.9+ is installed.

```bash
pip install pint
```

--------------------------------

### Install pre-commit Hook

Source: https://pint.readthedocs.io/en/stable/_sources/dev/contributing.rst

Install the pre-commit framework and set up the git hook. This automates code linting and formatting checks before commits.

```bash
pip install pre-commit
```

```bash
pre-commit install
```

--------------------------------

### Install currency_converter

Source: https://pint.readthedocs.io/en/stable/advanced/currencies.html

Command to install the external currency_converter dependency.

```bash
pip install currencyconverter
```

--------------------------------

### Run Python Shell with Pixi

Source: https://pint.readthedocs.io/en/stable/_sources/dev/contributing.rst

Start an interactive Python shell with Pint and its dependencies installed using pixi. Useful for development and debugging.

```bash
pixi run --environment test-py313-all python
```

--------------------------------

### Install Pint and Test Dependencies with pip

Source: https://pint.readthedocs.io/en/stable/_sources/dev/contributing.rst

Install Pint in editable mode along with its test dependencies using pip. The '.[test]' syntax installs optional dependencies for testing.

```bash
pip install -e '.[test]'
```

--------------------------------

### Set up environment with conda/pip on Windows

Source: https://pint.readthedocs.io/en/stable/dev/contributing.html

Manual setup instructions for Windows users using Conda.

```bash
$ conda install pip
$ conda install git
$ pip install -e ".[test]"
$ pip install -r requirements_docs.txt
$ pip install pre-commit
$ pre-commit install
```

--------------------------------

### Verify Pint Installation in Python

Source: https://pint.readthedocs.io/en/stable/_sources/getting/index.rst

After installation, you can verify Pint is working by importing it in a Python interpreter and checking its version.

```python
>>> import pint
>>> pint.__version__  # doctest: +SKIP
```

--------------------------------

### Pint Module Initialization

Source: https://pint.readthedocs.io/en/stable/_modules/pint.html

Core module setup including imports, registry initialization, and version detection.

```python
"""
pint
~~~~

Pint is Python module/package to define, operate and manipulate
**physical quantities**: the product of a numerical value and a
unit of measurement. It allows arithmetic operations between them
and conversions from and to different units.

:copyright: 2016 by Pint Authors, see AUTHORS for more details.
:license: BSD, see LICENSE for more details.
"""

from __future__ import annotations

from importlib.metadata import version

from .delegates.formatter._format_helpers import formatter
from .errors import (  # noqa: F401
    DefinitionSyntaxError,
    DimensionalityError,
    LogarithmicUnitCalculusError,
    OffsetUnitCalculusError,
    PintError,
    RedefinitionError,
    UndefinedUnitError,
    UnitStrippedWarning,
)
from .formatting import register_unit_format
from .registry import ApplicationRegistry, LazyRegistry, UnitRegistry
from .util import logger, pi_theorem  # noqa: F401

# Default Quantity, Unit and Measurement are the ones
# build in the default registry.
Quantity = UnitRegistry.Quantity
Unit = UnitRegistry.Unit
Measurement = UnitRegistry.Measurement
Context = UnitRegistry.Context
Group = UnitRegistry.Group

try:  # pragma: no cover
    __version__ = version("pint")
except Exception:  # pragma: no cover
    # we seem to have a local copy not installed without setuptools
    # so the reported version will be unknown
    __version__ = "unknown"


#: A Registry with the default units and constants.
_DEFAULT_REGISTRY = LazyRegistry()

#: Registry used for unpickling operations.
application_registry = ApplicationRegistry(_DEFAULT_REGISTRY)
```

--------------------------------

### Initialize Pint with NumPy

Source: https://pint.readthedocs.io/en/stable/user/numpy.html

Setup the UnitRegistry and Quantity class to enable NumPy support.

```python
from __future__ import annotations

import numpy as np

# Import Pint
import pint

ureg = pint.UnitRegistry()
Q_ = ureg.Quantity

# Silence NEP 18 warning
import warnings

with warnings.catch_warnings():
    warnings.simplefilter("ignore")
    Q_([])
```

--------------------------------

### Install Conda and Git

Source: https://pint.readthedocs.io/en/stable/_sources/dev/contributing.rst

Install pip and git using conda. These are prerequisites for setting up the development environment on Windows with Conda.

```bash
conda install pip
```

```bash
conda install git
```

--------------------------------

### Install currency_converter Package

Source: https://pint.readthedocs.io/en/stable/_sources/advanced/currencies.rst

Install the necessary currency_converter package using pip. This package is required for advanced currency conversions with Pint.

```bash
pip install currencyconverter
```

--------------------------------

### Pint Quantity Wrapping Sparse COO Example

Source: https://pint.readthedocs.io/en/stable/_sources/user/numpy.ipynb

Shows how a Pint Quantity can wrap a sparse COO array. This example creates a large sparse array, converts it to a Pint Quantity with units, and then prints the quantity and its mean value.

```python
from sparse import COO

np.random.seed(80243963)

x = np.random.random((100, 100, 100))
x[x < 0.9] = 0  # fill most of the array with zeros
s = COO(x)

q = s * ureg.m

print(q)
print()
print(np.mean(q))
```

--------------------------------

### Install Documentation Requirements with pip

Source: https://pint.readthedocs.io/en/stable/_sources/dev/contributing.rst

Install packages required for building documentation using pip. This ensures all necessary tools are available.

```bash
pip install -r requirements_docs.txt
```

--------------------------------

### Basic String Formatting Examples

Source: https://pint.readthedocs.io/en/stable/_sources/user/formatting.rst

Demonstrates various string formatting options for Pint quantities using f-strings and different format specifiers.

```python
>>> import pint
>>> ureg = pint.UnitRegistry()
>>> q = 2.3e-6 * ureg.m ** 3 / (ureg.s ** 2 * ureg.kg)
>>> f"{q:~P}"  # short pretty
'2.3×10⁻⁶ m³/kg/s²'
```

```python
>>> f"{q:~^P}"  # short pretty with negative exponents
'2.3×10⁻⁶ kg⁻¹·m³·s⁻²'
```

```python
>>> f"{q:~#P}"  # compact short pretty
'2.3 mm³/g/s²'
```

```python
>>> f"{q:#~}"  # short compact default
'2.3 mm ** 3 / g / s ** 2'
```

```python
>>> f"{q:.2f~#P}"  # short compact pretty with 2 float digits
'2.30 mm³/g/s²'
```

--------------------------------

### Install Pint using conda

Source: https://pint.readthedocs.io/en/stable/_sources/getting/index.rst

Install Pint from the conda-forge channel using Anaconda or Miniconda. This is an alternative to pip installation.

```bash
conda install -c conda-forge pint
```

--------------------------------

### ApplicationRegistry.get

Source: https://pint.readthedocs.io/en/stable/_modules/pint/registry.html

Get the wrapped registry.

```APIDOC
## get()

### Description
Retrieves the underlying registry instance wrapped by the ApplicationRegistry.
```

--------------------------------

### Integrate currency_converter with Pint for historical rates

Source: https://pint.readthedocs.io/en/stable/_sources/advanced/currencies.rst

This example demonstrates setting up Pint with the currency_converter library to handle currency conversions using historical rates. It defines custom units for each currency and adds a programmatic context for transformations.

```python
import itertools
import pint
import currency_converter
from datetime import date

# create a currency converter instance to load all of the data
cc = currency_converter.CurrencyConverter(fallback_on_missing_rate=True)

# load custom units and instantiate Quantity base class that is used everywhere
ureg = pint.UnitRegistry()
for c in cc.currencies:
    ureg.define(f"{c} = [currency_{c}]")  # i.e. USD = [currency_USD]

# add programmatic context for currency conversion
currency_context = pint.Context("FX", defaults={"date": None})
for a, b in itertools.combinations(list(cc.currencies), 2):
    def a2b(_ureg, x, date=None, a=a, b=b):
        return cc.convert(x.magnitude, a, b, date=date) * _ureg(b)
    def b2a(_ureg, x, date=None, a=a, b=b):
        return cc.convert(x.magnitude, b, a, date=date) * _ureg(a)
    currency_context.add_transformation(f"[currency_{a}]", f"[currency_{b}]", a2b)
    currency_context.add_transformation(f"[currency_{b}]", f"[currency_{a}]", b2a)
ureg.add_context(currency_context)

# Example usage
q = ureg.Quantity("1 EUR")
```

--------------------------------

### xarray Wrapping Pint Quantity Example

Source: https://pint.readthedocs.io/en/stable/_sources/user/numpy.ipynb

Demonstrates how an xarray DataArray can wrap a Pint Quantity. This example loads sample air temperature data, converts it to a Pint Quantity, and then prints the resulting xarray DataArray and its maximum value.

```python
import xarray as xr

# Load tutorial data
air = xr.tutorial.load_dataset("air_temperature")["air"][0]

# Convert to Quantity
air.data = Q_(air.data, air.attrs.pop("units", ""))

print(air)
print()
print(air.max())
```

--------------------------------

### Simple Unit Converter using String Parsing

Source: https://pint.readthedocs.io/en/stable/_sources/getting/tutorial.rst

A concise example of building a unit converter using Pint's string parsing capabilities.

```python
>>> user_input = '2.54 * centimeter to inch'
>>> src, dst = user_input.split(' to ')
>>> Q_(src).to(dst)
<Quantity(1.0, 'inch')>
```

--------------------------------

### Compound Unit Parsing Comparison

Source: https://pint.readthedocs.io/en/stable/_sources/user/log_units.rst

Compares parsing of compound units. The first example shows a known parsing issue, while the subsequent examples demonstrate correct parsing when using the `ureg()` constructor or `Q_()` with explicit units.

```python
-161.0 * ureg('dBm/Hz') == (-161.0 * ureg.dBm / ureg.Hz)
```

```python
ureg('-161.0 dBm/Hz') == (-161.0 * ureg.dBm / ureg.Hz)
```

```python
Q_(-161.0, 'dBm') / ureg.Hz == (-161.0 * ureg.dBm / ureg.Hz)
```

--------------------------------

### Define unit variants in definitions file

Source: https://pint.readthedocs.io/en/stable/user/contexts.html

Example of multiple BTU definitions provided in the default Pint definitions file.

```text
british_thermal_unit = 1055.056 * joule = Btu = BTU = Btu_iso
international_british_thermal_unit = 1e3 * pound / kilogram * degR / kelvin * international_calorie = Btu_it
thermochemical_british_thermal_unit = 1e3 * pound / kilogram * degR / kelvin * calorie = Btu_th
```

--------------------------------

### Perform currency conversion with defined transformations

Source: https://pint.readthedocs.io/en/stable/_sources/advanced/currencies.rst

Use a context to perform currency conversions with defined transformations. This example shows converting EUR to GBP and back to EUR.

```python
q = ureg.Quantity("1 EUR")
with ureg.context("FX"):
 q = q.to("GBP").to("EUR")
q
```

--------------------------------

### Register and Serialize with `serialize_` package

Source: https://pint.readthedocs.io/en/stable/_sources/advanced/serialization.rst

Use the `serialize_` package to register Pint Quantity objects and serialize them to formats like YAML. Ensure the `serialize` package is installed.

```python
>>> from serialize import dump, load, register_class
>>> register_class(ureg.Quantity, ureg.Quantity.to_tuple, ureg.Quantity.from_tuple)
>>> dump(duration, 'output.yaml')
>>> r = load('output.yaml')
```

--------------------------------

### Import NumPy and Pint

Source: https://pint.readthedocs.io/en/stable/_sources/user/numpy.ipynb

Import NumPy and Pint, and initialize a UnitRegistry and Quantity object. This setup is required for using Pint with NumPy arrays.

```python
# Import NumPy
from __future__ import annotations

import numpy as np

# Import Pint
import pint

ureg = pint.UnitRegistry()
Q_ = ureg.Quantity

# Silence NEP 18 warning
import warnings

with warnings.catch_warnings():
    warnings.simplefilter("ignore")
    Q_([])
```

--------------------------------

### Run Doctests with Pixi

Source: https://pint.readthedocs.io/en/stable/_sources/dev/contributing.rst

Execute doctests within the project's documentation using pixi. This verifies that examples in the documentation are correct.

```bash
pixi run doctest
```

--------------------------------

### Run Sphinx Doctests

Source: https://pint.readthedocs.io/en/stable/_sources/dev/contributing.rst

Execute doctests using Sphinx from the 'docs' directory. This verifies code examples within the documentation.

```bash
cd docs
make doctest
```

--------------------------------

### xarray with Pint Quantity, Dask, and Sparse COO

Source: https://pint.readthedocs.io/en/stable/_sources/user/numpy.ipynb

Integrate xarray with Pint Quantities, Dask arrays, and Sparse COO format. This example shows how to create a DataArray with units and sparse data, and then perform selections and aggregations.

```python
import dask.array as da

x = da.random.random((100, 100, 100), chunks=(100, 1, 1))
x[x < 0.95] = 0

data = xr.DataArray(
    Q_(x.map_blocks(COO), "m"),
    dims=("z", "y", "x"),
    coords={
        "z": np.arange(100),
        "y": np.arange(100) - 50,
        "x": np.arange(100) * 1.5 - 20,
    },
    name="test",
)

print(data)
print()
print(data.sel(x=125.5, y=-46).mean())
```

--------------------------------

### Spectroscopy Context Definition Syntax

Source: https://pint.readthedocs.io/en/stable/_sources/user/contexts.rst

Provides an example of the text-based syntax for defining a custom context, including parameters, dimensions, and conversion rules.

```text
@context(n=1) spectroscopy = sp
    # n index of refraction of the medium.
    [length] <-> [frequency]: speed_of_light / n / value
    [frequency] -> [energy]: planck_constant * value
    [energy] -> [frequency]: value / planck_constant
@end
```

--------------------------------

### Wrap function with mixed return values and units

Source: https://pint.readthedocs.io/en/stable/_sources/advanced/wrapping.rst

This example shows how to wrap a function with multiple return values where some have specified units and others do not. `None` is used to indicate unspecified units for airmass.

```python
@ureg.wraps(('deg', 'deg'), ('deg', 'deg', 'millibar', 'degC'))
def solar_position(lat, lon, press, tamb, timestamp):
    return zenith, azimuth, airmass
```

--------------------------------

### pint.setup_matplotlib

Source: https://pint.readthedocs.io/en/stable/api/base.html

Set up handlers for matplotlib’s unit support.

```APIDOC
## setup_matplotlib(enable: bool = True)

### Description
Set up handlers for matplotlib’s unit support.

### Parameters
- **enable** (bool) - Optional - Whether support should be enabled or disabled (Default: True).
```

--------------------------------

### Build Documentation with Pixi

Source: https://pint.readthedocs.io/en/stable/_sources/dev/contributing.rst

Build the project's documentation using pixi. This command is used to generate the documentation website.

```bash
pixi run docbuild
```

--------------------------------

### Retrieve a System

Source: https://pint.readthedocs.io/en/stable/_modules/pint/facets/system/registry.html

Use get_system to fetch a registered system by name, optionally creating it if it does not exist.

```python
def get_system(self, name: str, create_if_needed: bool = True) -> objects.System:
    """Return a Group.

    Parameters
    ----------
    name : str
        Name of the group to be.
    create_if_needed : bool
        If True, create a group if not found. If False, raise an Exception.
        (Default value = True)

    Returns
    -------
    type
        System

    """
    if name in self._systems:
        return self._systems[name]

    if not create_if_needed:
        raise ValueError("Unknown system %s" % name)

    return self.System(name)
```

--------------------------------

### UnitRegistry.setup_matplotlib

Source: https://pint.readthedocs.io/en/stable/_modules/pint/registry.html

Set up handlers for matplotlib's unit support.

```APIDOC
## setup_matplotlib(enable=True)

### Description
Set up handlers for matplotlib's unit support. This method delays importing matplotlib until it is actually requested.

### Parameters
- **enable** (bool) - Optional - Whether support should be enabled or disabled (Default value = True).
```

--------------------------------

### Install Pint with Conda/pip

Source: https://pint.readthedocs.io/en/stable/_sources/dev/contributing.rst

Install Pint in editable mode with test dependencies using pip within a Conda environment. This command is used on Windows.

```bash
pip install -e "'.[test]'"
```

--------------------------------

### Navigate to Pint Directory

Source: https://pint.readthedocs.io/en/stable/_sources/dev/contributing.rst

Change the current directory to the cloned Pint repository.

```bash
cd pint
```

--------------------------------

### Define Density Quantity

Source: https://pint.readthedocs.io/en/stable/_sources/getting/tutorial.rst

Example of defining a density quantity using grams and centimeters.

```python
density = 1.4 * ureg.gram / ureg.cm**3
```

--------------------------------

### Initialize UnitRegistry with a system

Source: https://pint.readthedocs.io/en/stable/user/systems.html

Set the default unit system during the initialization of the UnitRegistry.

```python
>>> import pint
>>> ureg = pint.UnitRegistry(system='mks')
>>> ureg.default_system
'mks'
```

--------------------------------

### Get Compatible Units

Source: https://pint.readthedocs.io/en/stable/_modules/pint/facets/plain/registry.html

Returns a set of units that are dimensionally compatible with the provided input units.

```python
def get_compatible_units(self, input_units: QuantityOrUnitLike) -> frozenset[UnitT]:
    """ """
    input_units = to_units_container(input_units)

    equiv = self._get_compatible_units(input_units)

    return frozenset(self.Unit(eq) for eq in equiv)
```

```python
def _get_compatible_units(
    self, input_units: UnitsContainer, *args, **kwargs
) -> frozenset[str]:
    """ """
    if not input_units:
        return frozenset()

    src_dim = self._get_dimensionality(input_units)
    return self._cache.dimensional_equivalents.setdefault(src_dim, frozenset())
```

--------------------------------

### Get fully qualified type name

Source: https://pint.readthedocs.io/en/stable/_modules/pint/compat.html

Retrieves the module and qualified name of a given type.

```python
def fully_qualified_name(t: type) -> str:
    """Return the fully qualified name of a type."""
    module = t.__module__
    name = t.__qualname__

    if module is None or module == "builtins":
        return name

    return f"{module}.{name}"
```

--------------------------------

### Build HTML Documentation

Source: https://pint.readthedocs.io/en/stable/_sources/dev/contributing.rst

Generate HTML documentation using Sphinx from the 'docs' directory. This command builds the project's documentation website.

```bash
cd docs
make html
```

--------------------------------

### Find Connected Nodes in a Graph

Source: https://pint.readthedocs.io/en/stable/_modules/pint/util.html

Recursively identifies all nodes connected to a starting node within a graph.

```python
def find_connected_nodes(
    graph: dict[TH, set[TH]], start: TH, visited: set[TH] | None = None
) -> set[TH] | None:
    """Find all nodes connected to a start node within a graph.

    Parameters
    ----------
    graph
        A graph given as a mapping of nodes
        to a set of all connected nodes to it.
    start
        Starting node.
    visited
        Mutable set to collect visited nodes.
        (default = None, empty set)

    Returns
    -------
    set[TH]
        The shortest path between two nodes.
    """

    # TODO: raise ValueError when start not in graph
    if start not in graph:
        return None

    visited = visited or set()
    visited.add(start)

    for node in graph[start]:
        if node not in visited:
            find_connected_nodes(graph, node, visited)

    return visited
```

--------------------------------

### Enable Registry Caching for Faster Instantiation

Source: https://pint.readthedocs.io/en/stable/_sources/advanced/performance.rst

Shows how to enable caching for Pint's UnitRegistry to significantly speed up instantiation, especially for large definition files. Specify a cache folder path to activate this experimental feature.

```python
import pint
ureg = pint.UnitRegistry(cache_folder="/my/cache/folder")
```

```python
import pint
ureg = pint.UnitRegistry(cache_folder=":auto:")
```

--------------------------------

### Get compatible units for a system

Source: https://pint.readthedocs.io/en/stable/_modules/pint/facets/system/registry.html

Public method to retrieve compatible units filtered by a specific group or system.

```python
def get_compatible_units(
        self, input_units: UnitsContainerT, group_or_system: str | None = None
    ) -> frozenset[Unit]:
        """ """

        group_or_system = group_or_system or self._default_system_name

        if group_or_system is None:
            return super().get_compatible_units(input_units)

        input_units = to_units_container(input_units)

        equiv = self._get_compatible_units(input_units, group_or_system)

        return frozenset(self.Unit(eq) for eq in equiv)
```

--------------------------------

### Initialize Dynamic Classes

Source: https://pint.readthedocs.io/en/stable/_modules/pint/facets/plain/registry.html

Generates and attaches Unit and Quantity subclasses to the registry instance.

```python
def _init_dynamic_classes(self) -> None:
    """Generate subclasses on the fly and attach them to self"""

    self.Unit = create_class_with_registry(self, self.Unit)
    self.Quantity = create_class_with_registry(self, self.Quantity)
```

--------------------------------

### Parameterized Context for Wavelength Conversion in Medium

Source: https://pint.readthedocs.io/en/stable/_sources/user/contexts.rst

Shows how to use a parameterized context ('spectroscopy' with 'n' for refractive index) to convert wavelength in air to wavelength in a medium (water).

```python
wl = 530. * ureg.nm
f = wl.to('Hz', 'sp')
f.to('nm', 'sp', n=1.33)
```

--------------------------------

### Get Quantity Dimensionality

Source: https://pint.readthedocs.io/en/stable/_sources/user/numpy.ipynb

Retrieve the dimensionality of a Pint Quantity array. This is useful for understanding the physical dimensions of the data.

```python
print(legs1.dimensionality)
```

--------------------------------

### Enable Multiple Contexts Globally

Source: https://pint.readthedocs.io/en/stable/_sources/user/contexts.rst

Shows how to enable multiple contexts ('sp' and 'boltzmann') globally for the unit registry.

```python
ureg.enable_contexts('sp', 'boltzmann')
```

--------------------------------

### Create Measurement Object

Source: https://pint.readthedocs.io/en/stable/_sources/advanced/measurement.rst

Create a measurement object from a quantity using the plus_minus() method. Ensure the 'uncertainties' package is installed.

```python
import numpy as np
from pint import UnitRegistry
ureg = UnitRegistry()
book_length = (20. * ureg.centimeter).plus_minus(2.)
print(book_length)
```

--------------------------------

### Get conversion factor between units

Source: https://pint.readthedocs.io/en/stable/_modules/pint/facets/plain/registry.html

Retrieves the conversion factor between two UnitsContainer objects, returning a DimensionalityError if the dimensions do not match.

```python
    def _get_conversion_factor(
        self, src: UnitsContainer, dst: UnitsContainer
    ) -> Scalar | DimensionalityError:
        """Get conversion factor in non-multiplicative units.

        Parameters
        ----------
        src
            Source units
        dst
            Target units

        Returns
        -------
            Conversion factor or DimensionalityError
        """
        cache = self._cache.conversion_factor
        try:
            return cache[(src, dst)]
        except KeyError:
            pass

        src_dim = self._get_dimensionality(src)
        dst_dim = self._get_dimensionality(dst)

        # If the source and destination dimensionality are different,
        # then the conversion cannot be performed.
        if src_dim != dst_dim:
            return DimensionalityError(src, dst, src_dim, dst_dim)

        # Here src and dst have only multiplicative units left. Thus we can
        # convert with a factor.
        factor, _ = self._get_root_units(src / dst)

        cache[(src, dst)] = factor
        return factor
```

--------------------------------

### Get canonical unit name

Source: https://pint.readthedocs.io/en/stable/_modules/pint/facets/plain/registry.html

Retrieves the canonical name for a given unit alias, handling prefixing and case sensitivity.

```python
    def get_name(self, name_or_alias: str, case_sensitive: bool | None = None) -> str:
        """Return the canonical name of a unit."""

        if name_or_alias == "dimensionless":
            return ""

        try:
            return self._units[name_or_alias].name
        except KeyError:
            pass

        candidates = self.parse_unit_name(name_or_alias, case_sensitive)
        if not candidates:
            raise UndefinedUnitError(name_or_alias)

        prefix, unit_name, _ = candidates[0]
        if len(candidates) > 1:
            logger.warning(
                f"Parsing {name_or_alias} yield multiple results. Options are: {candidates!r}"
            )

        if prefix:
            if not self._units[unit_name].is_multiplicative:
                raise OffsetUnitCalculusError(
                    "Prefixing a unit requires multiplying the unit."
                )

            name = prefix + unit_name
            symbol = self.get_symbol(name, case_sensitive)
            prefix_def = self._prefixes[prefix]
            self._units[name] = UnitDefinition(
                name,
                symbol,
                tuple(),
                prefix_def.converter,
                self.UnitsContainer({unit_name: 1}),
            )
            return prefix + unit_name

        return unit_name
```

--------------------------------

### ApplicationRegistry.set

Source: https://pint.readthedocs.io/en/stable/_modules/pint/registry.html

Set the new registry.

```APIDOC
## set(new_registry)

### Description
Updates the application registry to a new instance.

### Parameters
- **new_registry** (ApplicationRegistry | LazyRegistry | UnitRegistry) - Required - The new registry instance to be set.
```

--------------------------------

### Registry Management Functions

Source: https://pint.readthedocs.io/en/stable/_modules/pint.html

Functions to get and set the global application registry used for unpickling and direct object instantiation.

```python
[docs]
def set_application_registry(registry):
    """Set the application registry, which is used for unpickling operations
    and when invoking pint.Quantity or pint.Unit directly.

    Parameters
    ----------
    registry : pint.UnitRegistry
    """
    application_registry.set(registry)




[docs]
def get_application_registry():
    """Return the application registry. If :func:`set_application_registry` was never
    invoked, return a registry built using :file:`defaults_en.txt` embedded in the pint
    package.

    Returns
    -------
    pint.UnitRegistry
    """
    return application_registry
```

--------------------------------

### Enable Multiple Contexts for Conversion

Source: https://pint.readthedocs.io/en/stable/_sources/user/contexts.rst

Demonstrates enabling multiple contexts ('sp' and 'boltzmann') simultaneously for a unit conversion.

```python
q.to('Hz', 'sp', 'boltzmann')
```

--------------------------------

### Registry Post-Initialization Hook

Source: https://pint.readthedocs.io/en/stable/_modules/pint/facets/plain/registry.html

Loads definitions from a file and builds the internal cache after the registry is initialized.

```python
def _after_init(self) -> None:
    """This should be called after all __init__"""

    if self._filename == "":
        path = pathlib.Path(__file__).parent.parent.parent / "default_en.txt"
        loaded_files = self.load_definitions(path, True)
    elif self._filename is not None:
        loaded_files = self.load_definitions(self._filename)
    else:
        loaded_files = None

    self._build_cache(loaded_files)
    self._initialized = True
```

--------------------------------

### Convert Wavelength to Frequency using Pint Context

Source: https://pint.readthedocs.io/en/stable/_sources/user/contexts.rst

Shows how to convert wavelength to frequency using the predefined 'spectroscopy' context in Pint, leveraging the relationship frequency = speed_of_light / wavelength.

```python
ureg.speed_of_light / q.to('Hz')
```

--------------------------------

### Context Object Initialization and Management

Source: https://pint.readthedocs.io/en/stable/_modules/pint/facets/context/objects.html

Methods for initializing the context container and managing the list of active contexts.

```python
def __init__(self):
    super().__init__()
    self.contexts: list[Context] = []
    self.maps.clear()  # Remove default empty map
    self._graph: dict[SrcDst, set[UnitsContainer]] | None = None

def insert_contexts(self, *contexts: Context):
    """Insert one or more contexts in reversed order the chained map.
    (A rule in last context will take precedence)

    To facilitate the identification of the context with the matching rule,
    the *relation_to_context* dictionary of the context is used.
    """

    self.contexts = list(reversed(contexts)) + self.contexts
    self.maps = [ctx.relation_to_context for ctx in reversed(contexts)] + self.maps
    self._graph = None

def remove_contexts(self, n: int | None = None):
    """Remove the last n inserted contexts from the chain.

    Parameters
    ----------
    n: int
        (Default value = None)
    """

    del self.contexts[:n]
    del self.maps[:n]
    self._graph = None
```

--------------------------------

### Add Specific Functionality to a Custom Registry

Source: https://pint.readthedocs.io/en/stable/_sources/advanced/custom-registry-class.rst

Extend a custom registry by adding new methods. This example adds 'my_specific_function' to a subclass of UnitRegistry.

```python
>>> import pint
>>> class MyRegistry(pint.UnitRegistry):
... 
...     def my_specific_function(self):
...         """Do something
...         """


```

--------------------------------

### Define a Custom Registry Subclass

Source: https://pint.readthedocs.io/en/stable/_sources/advanced/custom-registry-class.rst

Create a custom registry by subclassing an existing Pint registry facet. This example shows subclassing NonMultiplicativeRegistry.

```python
>>> import pint
>>> class MyRegistry(pint.facets.NonMultiplicativeRegistry):
...     pass

```

--------------------------------

### Run Benchmarks with Pixi

Source: https://pint.readthedocs.io/en/stable/_sources/dev/contributing.rst

Execute benchmarks along with tests using pixi. This process is significantly slower and rarely required.

```bash
pixi run --environment test-py313-all bench
```

--------------------------------

### Instantiate a shared registry

Source: https://pint.readthedocs.io/en/stable/getting/pint-in-your-projects.html

Initialize the UnitRegistry and Quantity class in a central location, such as the package's __init__.py file.

```python
>>> from pint import UnitRegistry
>>> ureg = UnitRegistry()
>>> Q_ = ureg.Quantity
```

--------------------------------

### Pushing release changes

Source: https://pint.readthedocs.io/en/stable/dev/contributing.html

Commit the transition back to development and push all tags to the repository.

```bash
$ git commit -a -m "Back to development: 0.25"
$ git push --tags
```

--------------------------------

### Convert Currency within a Context

Source: https://pint.readthedocs.io/en/stable/_sources/advanced/currencies.rst

Use a context manager to perform currency conversions to a specific currency for a given date. Ensure the currency_converter package is installed.

```python
from datetime import date

with ureg.context("FX", date=date(2010, 11, 21)):
    q = q.to("USD")
print(q)
```

--------------------------------

### Define and use a Context for unit transformations

Source: https://pint.readthedocs.io/en/stable/_modules/pint/facets/context/objects.html

Demonstrates creating a Context, adding transformation functions between dimensions, and performing conversions with optional parameters.

```python
>>> from pint.util import UnitsContainer
>>> from pint import Context, UnitRegistry
>>> ureg = UnitRegistry()
>>> timedim = UnitsContainer({"[time]": 1})
>>> spacedim = UnitsContainer({"[length]": 1})
>>> def time_to_len(ureg, time):
...     "Time to length converter"
...     return 3.0 * time
>>> c = Context()
>>> c.add_transformation(timedim, spacedim, time_to_len)
>>> c.transform(timedim, spacedim, ureg, 2)
6.0
>>> def time_to_len_indexed(ureg, time, n=1):
...     "Time to length converter, n is the index of refraction of the material"
...     return 3.0 * time / n
>>> c = Context(defaults={"n": 3})
>>> c.add_transformation(timedim, spacedim, time_to_len_indexed)
>>> c.transform(timedim, spacedim, ureg, 2)
2.0
>>> c.redefine("pound = 0.5 kg")
```

--------------------------------

### Format Units on Plot

Source: https://pint.readthedocs.io/en/stable/_sources/user/plotting.rst

Change the format of units displayed on the plot using a custom formatter string. This example uses '{:~P}' for a specific unit representation.

```python
import matplotlib.pyplot as plt
import numpy as np
import pint

ureg = pint.UnitRegistry()
ureg.setup_matplotlib(True)

ureg.mpl_formatter = "{:~P}"

y = np.linspace(0, 30) * ureg.miles
x = np.linspace(0, 5) * ureg.hours

fig, ax = plt.subplots()
ax.yaxis.set_units(ureg.inches)
ax.xaxis.set_units(ureg.seconds)

ax.plot(x, y, 'tab:blue')
ax.axhline(26400 * ureg.feet, color='tab:red')
ax.axvline(120 * ureg.minutes, color='tab:green')
```

--------------------------------

### Initialize Unit Registry with a Specific System

Source: https://pint.readthedocs.io/en/stable/_sources/user/systems.rst

Initialize a Pint UnitRegistry with a specified system, such as 'mks'. This sets the default system for base unit conversions.

```python
import pint
ureg = pint.UnitRegistry(system='mks')
print(ureg.default_system)
```

--------------------------------

### Defining unit relations between arguments

Source: https://pint.readthedocs.io/en/stable/advanced/wrapping.html

Use strings starting with '=' to define unit relationships between arguments, where labels like 'A' or 'B' represent consistent units.

```python
>>> @ureg.wraps('=A**2', ('=A', '=A'))
... def sqsum(x, y):
...     return x * x  + 2 * x * y + y * y
```

```python
>>> @ureg.wraps('=A**2*B', ('=A', '=A*B', '=B'))
... def some_function(x, y, z):
...     pass
```

```python
>>> @ureg.wraps('=A*B', ('=A', '=B'))
... def get_displacement(time, rate=Q_(1, 'm/s')):
...     return time * rate
...
>>> get_displacement(Q_(2, 's'))
<Quantity(2, 'meter')>
>>> get_displacement(Q_(2, 's'), Q_(1, 'deg/s'))
<Quantity(2, 'degree')>
```

--------------------------------

### Initialize UnitRegistry

Source: https://pint.readthedocs.io/en/stable/_sources/getting/tutorial.rst

Initialize a UnitRegistry object to store unit definitions and handle conversions. This is the first step before using Pint.

```python
from pint import UnitRegistry
ureg = UnitRegistry()
```

--------------------------------

### Initialize optional dependency flags

Source: https://pint.readthedocs.io/en/stable/_modules/pint/compat.html

Attempts to import optional libraries and sets boolean flags to track their availability.

```python
try:
    import babel  # noqa: F401
    from babel import units as babel_units

    HAS_BABEL = hasattr(babel_units, "format_unit")
except ImportError:
    HAS_BABEL = False

try:
    import uncertainties  # noqa: F401

    HAS_UNCERTAINTIES = True
except ImportError:
    HAS_UNCERTAINTIES = False

try:
    import numpy  # noqa: F401

    HAS_NUMPY = True
except ImportError:
    HAS_NUMPY = False

try:
    import scipy  # noqa: F401

    HAS_SCIPY = True
except ImportError:
    HAS_SCIPY = False

HAS_DASK = find_spec("dask") is not None
```

--------------------------------

### Demonstrate ValueError with Different Registries

Source: https://pint.readthedocs.io/en/stable/_sources/getting/pint-in-your-projects.rst

This example demonstrates the error that occurs when attempting to operate on quantities from different Pint registries. It highlights the importance of using a single, shared registry.

```python
q1 = 10 * UnitRegistry().meter
q2 = 10 * UnitRegistry().meter
q1 + q2
```

--------------------------------

### Ignore argument conversion using @ureg.wraps with None

Source: https://pint.readthedocs.io/en/stable/_sources/advanced/wrapping.rst

Shows how to use @ureg.wraps to ignore the unit conversion for a specific argument by passing None. This example uses a hypothetical pendulum_period_error function.

```python
mypp3 = ureg.wraps((ureg.second, None), ureg.meter)(pendulum_period_error)
```

--------------------------------

### Nested Wrapping: xarray, Dask, and Sparse COO

Source: https://pint.readthedocs.io/en/stable/user/numpy.html

An advanced example showing an xarray DataArray wrapping a Pint Quantity, which in turn wraps a Dask array containing Sparse COO data.

```python
import dask.array as da

x = da.random.random((100, 100, 100), chunks=(100, 1, 1))
x[x < 0.95] = 0

data = xr.DataArray(
    Q_(x.map_blocks(COO), "m"),
    dims=("z", "y", "x"),
    coords={
        "z": np.arange(100),
        "y": np.arange(100) - 50,
        "x": np.arange(100) * 1.5 - 20,
    },
    name="test",
)

print(data)
print()
print(data.sel(x=125.5, y=-46).mean())
```

--------------------------------

### Enable Spectroscopy Context Globally for Registry

Source: https://pint.readthedocs.io/en/stable/_sources/user/contexts.rst

Demonstrates enabling the 'spectroscopy' context globally for the entire unit registry, so it applies to all subsequent operations.

```python
ureg.enable_contexts('sp')
```

--------------------------------

### Convert Base Units to Logarithmic Units

Source: https://pint.readthedocs.io/en/stable/_sources/user/log_units.rst

Convert a base unit quantity back to a logarithmic unit using the `.to()` method. This example shows converting milliwatts to dBm and a dimensionless quantity to octaves.

```python
(100.0 * ureg('mW')).to('dBm')
```

```python
shift = Q_(4, '')
shift.to('octave')
```

--------------------------------

### Default Format String

Source: https://pint.readthedocs.io/en/stable/_sources/user/formatting.rst

Shows how to set and use the default format string for Pint quantities when no explicit format is provided.

```python
>>> ureg.formatter.default_format = "P"
>>> f"{q}"
'2.3×10⁻⁶ meter³/kilogram/second²'
```

--------------------------------

### get_system

Source: https://pint.readthedocs.io/en/stable/api/facets.html

Retrieves a system (Group) by name, with an option to create it if it does not exist.

```APIDOC
## get_system(name, create_if_needed=True)

### Description
Return a Group (System) by its name.

### Parameters
- **name** (str) - Required - Name of the group.
- **create_if_needed** (bool) - Optional - If True, create a group if not found. If False, raise an Exception. (Default: True)

### Returns
- **System** - The requested system object.
```

--------------------------------

### Basic Quantity Addition in Pint

Source: https://pint.readthedocs.io/en/stable/_sources/getting/overview.rst

Demonstrates adding quantities with different units using Pint's UnitRegistry. Ensure UnitRegistry is initialized before use.

```python
>>> import pint
>>> ureg = pint.UnitRegistry()
>>> 3 * ureg.meter + 4 * ureg.cm
<Quantity(3.04, 'meter')>
```

--------------------------------

### Pint Quantity Wrapping NumPy Masked Array Example

Source: https://pint.readthedocs.io/en/stable/_sources/user/numpy.ipynb

Illustrates wrapping a NumPy masked array with a Pint Quantity. It shows the correct way to create the Quantity using the `Quantity` class and warns against using multiplication until a known NumPy issue is resolved.

```python
m = np.ma.masked_array([2, 3, 5, 7], mask=[False, True, False, True])

# Must create using Quantity class
print(repr(ureg.Quantity(m, "m")))
print()

# DO NOT create using multiplication until
# https://github.com/numpy/numpy/issues/15200 is resolved, as
# unexpected behavior may result
print(repr(m * ureg.m))
```

--------------------------------

### Perform basic unit arithmetic

Source: https://pint.readthedocs.io/en/stable/getting/overview.html

Demonstrates creating a unit registry and performing addition between different length units.

```python
>>> import pint
>>> ureg = pint.UnitRegistry()
>>> 3 * ureg.meter + 4 * ureg.cm
<Quantity(3.04, 'meter')>
```

--------------------------------

### Configure dependency-specific constants

Source: https://pint.readthedocs.io/en/stable/_modules/pint/compat.html

Sets up global constants and imports based on the availability of optional dependencies.

```python
if HAS_BABEL:
    from babel import Locale
    from babel import units as babel_units

    babel_parse = Locale.parse
else:
    babel_parse = missing_dependency("Babel")  # noqa: F811 # type:ignore
    babel_units = babel_parse
    Locale = missing_dependency

if HAS_UNCERTAINTIES:
    from uncertainties import UFloat, ufloat

    unp = None
else:
    UFloat = ufloat = unp = None
```
Tokens:
Raw