Source code for saiunit._base_unit

# Copyright 2026 BrainX Ecosystem Limited. All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# ==============================================================================

from __future__ import annotations

import math
import numbers
import threading
from typing import TYPE_CHECKING, Any

from . import _unit_parse
from ._base_dimension import (
    Dimension,
    DIMENSIONLESS,
    _is_tracer,
    get_or_create_dimension,
)
from ._typing import ArrayLike
from ._unit_format import STYLES, render
from ._unit_terms import (
    PRE_ONE,
    Atom,
    Exp,
    Pre,
    Terms,
    combine_terms,
    derive_dim,
    derive_magnitude,
    latex_mathrm,
    make_atom,
    norm_exp,
    norm_scale,
)

if TYPE_CHECKING:
    from ._base_quantity import Quantity

__all__ = [
    'Unit',
    'UNITLESS',
    'add_standard_unit',
    'parse_unit',
]

# SI unit _prefixes as integer exponents of 10, see table at end of file.
_siprefixes = {
    "y": -24,
    "z": -21,
    "a": -18,
    "f": -15,
    "p": -12,
    "n": -9,
    "u": -6,
    "m": -3,
    "c": -2,
    "d": -1,
    "": 0,
    "da": 1,
    "h": 2,
    "k": 3,
    "M": 6,
    "G": 9,
    "T": 12,
    "P": 15,
    "E": 18,
    "Z": 21,
    "Y": 24,
}


# ---------------------------------------------------------------------------
# Registries
# ---------------------------------------------------------------------------

def _assert_same_base(u1, u2):
    if not u1.has_same_base(u2):
        raise TypeError(f"Cannot operate on units with different bases. Got {u1.base} != {u2.base}.")


_standard_units: 'dict[tuple, Unit]' = {}
_standard_unit_aliases: 'dict[tuple, list[Unit]]' = {}
_unit_name_registry: 'dict[str, Unit]' = {}
# Alternative spellings accepted by the parser but never rendered by
# ``str()``: Unicode symbols (``µm``, ``Ω``, ``°``) of registered units.
_symbol_aliases: 'dict[str, Unit]' = {}
# Curated targets for automatic simplification during unit arithmetic,
# keyed like ``_standard_units``.  Only units registered with
# ``auto_simplify=True`` (SI base units, N, Pa, J, W, C, V, F, ohm, S, Hz
# and their prefixed forms) appear here, so ``mV * ms`` stays ``mV * ms``
# rather than collapsing onto ``uWb``.
_auto_targets: 'dict[tuple, list[Atom]]' = {}
_auto_atoms: 'set[Atom]' = set()
# Monotonically-increasing registration index for each registered Unit
# identity.  Used by :func:`_select_preferred_standard_unit` to prefer
# units that were registered earlier (i.e. library built-ins) over
# user-added aliases for the same physical key.
# Entries are never evicted, but this is safe: the key is ``id(u)``, and
# every registered ``u`` stays alive for the process lifetime via the
# strong reference held in ``_standard_unit_aliases``, so an id can never
# be recycled and silently collide with a later, unrelated Unit.
_unit_registration_index: 'dict[int, int]' = {}
_next_registration_index: 'list[int]' = [0]
# Guards all registry mutation in ``add_standard_unit`` so concurrent
# registration (e.g. user threads importing unit-defining modules) cannot
# interleave alias-list updates with preferred-unit selection.
_registry_lock = threading.Lock()

# ---------------------------------------------------------------------------
# Ambiguous-key detection
#
# A dimension key is "ambiguous" when >=2 registered aliases have
# **different display names** (dispname).  Spelling variants like
# meter/metre share the same dispname ("m") so they are NOT flagged.
# Genuine semantic collisions like hertz/becquerel ("Hz" vs "Bq") ARE
# flagged automatically—no hardcoded list required.
#
# Ambiguous keys are never auto-substituted during unit composition, so
# that e.g. joule/kg never silently becomes sievert.
# ---------------------------------------------------------------------------
_ambiguous_keys: set = set()


def _standard_unit_preference_score(unit: 'Unit') -> int:
    """
    Return a preference score for choosing canonical display aliases.

    Lower is better.  Deterministic: on ties the name that sorts first
    alphabetically wins (via ``_select_preferred_standard_unit``).
    """
    name = unit.name.lower() if isinstance(unit.name, str) else ""
    score = 0
    # Prefer frequency over radioactivity for s^-1
    if "hertz" in name:
        score -= 10
    return score


def _select_preferred_standard_unit(units: 'list[Unit]') -> 'Unit':
    """Pick the preferred alias.

    Order of preference (lower is better):

    1. ``_standard_unit_preference_score`` (e.g. prefer hertz over
       becquerel for s^-1).
    2. Registration index — library built-ins win over user
       additions made via :func:`add_standard_unit` after import,
       so user aliases cannot hijack canonical display.
    3. Alphabetical, as a final deterministic tie-breaker for units
       registered in the same call.
    """
    def _key(u):
        idx = _unit_registration_index.get(id(u), float('inf'))
        return (
            _standard_unit_preference_score(u),
            idx,
            u.name.lower() if isinstance(u.name, str) else "",
        )
    return min(units, key=_key)


[docs] def add_standard_unit(u: 'Unit', *, auto_simplify: bool = False): """ Register a unit as a standard unit. Registered units are recognised by :func:`parse_unit` (by name and display name) and are the targets of :meth:`Unit.simplify`. If multiple units are registered for the same key, the preferred alias is selected automatically. Keys with two or more distinct display names are flagged as *ambiguous*. Parameters ---------- u : Unit The unit to register. Its ``base``, ``scale``, and ``factor`` must all be plain Python ``int`` or ``float`` values (not JAX tracers) for registration to take effect. auto_simplify : bool, optional If True, unit arithmetic whose result has exactly this unit's dimension and magnitude is displayed as this unit (e.g. ``kg * m / s^2`` displays as ``N``). Only meaningful for a named (non-composite) unit. Defaults to False. Examples -------- .. code-block:: python >>> import saiunit as u >>> my_unit = u.Unit( ... dim=u.joule.dim, ... name='my_energy', ... dispname='myE', ... is_fullname=True, ... ) >>> u.add_standard_unit(my_unit) """ if ( isinstance(u.base, (int, float)) and isinstance(u.scale, (int, float)) and isinstance(u.factor, (int, float)) ): with _registry_lock: key = (u.dim, u.scale, u.base, u.factor) aliases = _standard_unit_aliases.setdefault(key, []) # Dedup by identity *and* by (name, dispname): re-running the # same ``Unit.create(...)`` call produces a new instance each # time; without value-based dedup, repeated registration grows # the alias list unboundedly and poisons the ambiguity # heuristic below. if not any( existing is u or (existing.name == u.name and existing.dispname == u.dispname) for existing in aliases ): aliases.append(u) # Stamp a monotonic registration index so that later # additions cannot hijack the canonical display. _unit_registration_index[id(u)] = _next_registration_index[0] _next_registration_index[0] += 1 _standard_units[key] = _select_preferred_standard_unit(aliases) # Auto-detect ambiguity: >=2 distinct display names → ambiguous dispnames = {a.dispname for a in aliases if isinstance(a.dispname, str)} if len(dispnames) >= 2: _ambiguous_keys.add(key) # Register by dispname and name for string-based lookup if isinstance(u.dispname, str) and u.dispname: _unit_name_registry.setdefault(u.dispname, u) if isinstance(u.name, str) and u.name: _unit_name_registry.setdefault(u.name, u) atom = u._single_atom() if atom is not None: if atom.unicode != atom.symbol: _symbol_aliases.setdefault(atom.unicode, u) if auto_simplify: targets = _auto_targets.setdefault(key, []) if atom not in targets: targets.append(atom) _auto_atoms.add(atom)
def _lookup_symbol(s: str) -> 'Unit | None': """Return the registered unit spelled *s* (name, symbol or alias).""" unit = _unit_name_registry.get(s) return unit if unit is not None else _symbol_aliases.get(s) _special_symbol_cache: 'list' = [None, ()] def _special_symbols() -> 'tuple[str, ...]': """Registered symbols that are not identifiers (``km/h``, ``oz t``, ``°``), longest first.""" stamp = (len(_unit_name_registry), len(_symbol_aliases)) if _special_symbol_cache[0] != stamp: keys = set(_unit_name_registry) | set(_symbol_aliases) specials = sorted((k for k in keys if _unit_parse.is_special_symbol(k)), key=lambda k: (-len(k), k)) _special_symbol_cache[:] = [stamp, tuple(specials)] return _special_symbol_cache[1] def parse_unit(s: str) -> 'Unit': """Parse a unit string into a :class:`Unit`. Accepts the strings produced by ``str(unit)``, ``repr(unit)`` and ``unit.to_string('unicode')``, e.g. ``"mV"``, ``"J / kg"``, ``"nA / cm^2"``, ``"mS·nA/cm²"``, ``"m^(1/3)"``, ``"10^3 * m"``. Both display names (``"mV"``) and full names (``"mvolt"``) are recognised, as are the Unicode symbols ``µ``/``μ``, ``Ω`` and ``°``. ``/`` binds looser than ``*``: ``"a / b * c"`` is ``a / (b * c)``. Parameters ---------- s : str The unit string to parse. Returns ------- Unit Raises ------ ValueError If the string cannot be parsed into a known unit. Examples -------- >>> parse_unit("mV") Unit("mV") >>> parse_unit("J / kg") Unit("J / kg") """ s = s.strip() # Strip the Unit("...") repr wrapper if present if s.startswith('Unit("') and s.endswith('")'): s = s[6:-2] elif s.startswith("Unit('") and s.endswith("')"): s = s[6:-2] if not s: raise ValueError("Cannot parse an empty unit string.") # Dimensionless if s == '1': return UNITLESS # Fast path: direct registry lookup (also covers registered names # containing spaces or parentheses, e.g. "troy pound") unit = _lookup_symbol(s) if unit is None: s = ' '.join(s.split()) unit = _lookup_symbol(s) if unit is not None: return unit return _unit_parse.parse(s, _lookup_symbol, _special_symbols()) def _normalise_scalar(x: Any) -> Any: """Coerce numpy/generic real scalars to plain ``int``/``float``. Standard-unit registration and lookup require plain Python numbers, so e.g. ``np.int64(3)`` must behave the same as ``3``. Non-Real objects (JAX tracers, arrays) pass through untouched, except for concrete 0-d arrays, which are unwrapped to their scalar value (a concrete 0-d array would otherwise construct a ``Unit`` whose ``hash()`` crashes). JAX tracers are left untouched so tracing under ``jit``/``vmap``/``grad`` keeps working. """ if isinstance(x, bool): return int(x) if isinstance(x, (int, float)): return x if isinstance(x, numbers.Integral): return int(x) if isinstance(x, numbers.Real): return float(x) if getattr(x, 'ndim', None) == 0 and not _is_tracer(x): try: return _normalise_scalar(x.item()) except (AttributeError, TypeError): pass return x def _validate_scale_and_factor(scale: Any, factor: Any) -> None: """Reject scale/factor values that poison Unit arithmetic. Non-finite scales break ``__eq__``/``__hash__`` (NaN is unequal to itself) and display; non-positive factors cannot represent a physical conversion and crash ``reverse()``/division (factor 0) or produce complex factors under fractional powers (negative factor). Values that are not plain real numbers (e.g. JAX tracers) are not checked. """ if isinstance(scale, complex) or isinstance(factor, complex): raise TypeError( f"Unit scale and factor must be real numbers; " f"got scale={scale!r}, factor={factor!r}." ) if isinstance(scale, int) and not isinstance(scale, bool): try: float(scale) except OverflowError: raise ValueError( f"Unit scale overflows the float range: {scale!r}." ) from None if isinstance(scale, (int, float)) and not math.isfinite(scale): raise ValueError( f"Unit scale must be a finite real number; got scale={scale!r}." ) if isinstance(factor, int) and not isinstance(factor, bool): try: float(factor) except OverflowError: raise ValueError( f"Unit factor overflows the float range: {factor!r}." ) from None if isinstance(factor, (int, float)): if not math.isfinite(factor): raise ValueError( f"Unit factor must be a finite real number; got factor={factor!r}." ) if factor <= 0: raise ValueError( f"Unit factor must be positive; got factor={factor!r}." ) class Unit: r""" A physical unit. Basically, a unit is just a number with given dimensions, e.g. mvolt = 0.001 with the dimensions of voltage. The units module defines a large number of standard units, and you can also define your own (see below). Mathematically, a unit represents: .. math:: \text{{factor}} \times \text{{base}}^{\text{{scale}}} \times \text{{dimension}} where the ``factor`` is the conversion factor of the unit (e.g. ``1 calorie = 4.18400 Joule``, so the factor is 4.18400), the ``base`` is the base of the exponent (e.g. 10 for the kilo prefix), the ``scale`` is the exponent of the base (e.g. 3 for the kilo prefix), and the ``dimension`` is the physical dimensions of the unit (e.g. ``joule`` for energy). The unit class also keeps track of the named units it was composed from, to generate a readable string representation. See below. Parameters ---------- dim : Dimension, optional The physical dimensions of the unit. Defaults to ``DIMENSIONLESS``. scale : array_like, optional The scale exponent, e.g. 3 for a "k" (kilo) prefix. Defaults to 0. base : array_like, optional The base of the exponent. Must be 10 (the only supported base); other values raise ``ValueError``. factor : array_like, optional The conversion factor of the unit. Must be positive. Defaults to 1. name : str, optional The full name of the unit, e.g. ``'volt'``. dispname : str, optional The display name, e.g. ``'V'``. is_fullname : bool, optional Whether ``name`` is the canonical full name. Defaults to ``True``. display_parts : list of tuple, optional Legacy ``(name, dispname, exponent)`` display components, accepted for backward compatibility (old pickles). Notes ----- When creating scaled units, you can use the following prefixes: ====== ====== ============== Factor Name Prefix ====== ====== ============== 10^24 yotta Y 10^21 zetta Z 10^18 exa E 10^15 peta P 10^12 tera T 10^9 giga G 10^6 mega M 10^3 kilo k 10^2 hecto h 10^1 deka da 1 10^-1 deci d 10^-2 centi c 10^-3 milli m 10^-6 micro u (\mu in SI) 10^-9 nano n 10^-12 pico p 10^-15 femto f 10^-18 atto a 10^-21 zepto z 10^-24 yocto y ====== ====== ============== **Display** A unit keeps the named units it was composed from, so composites display the way they were written: ``u.mS * u.nA / u.cm ** 2`` is ``mS * nA / cm^2`` and ``u.mV * u.ms`` is ``ms * mV``. Terms are ordered canonically (numerator first, then by symbol), so ``a * b`` and ``b * a`` display identically. A composite collapses automatically only onto a curated set of units (SI base units, N, Pa, J, W, C, V, F, ohm, S, Hz and their prefixed forms): .. code-block:: python >>> import saiunit as u >>> u.kilogram * u.metre / u.second ** 2 Unit("N") >>> u.volt * u.second Unit("s * V") >>> (u.volt * u.second).simplify() Unit("Wb") ``str(unit)`` is canonical ASCII that :func:`parse_unit` reads back; :meth:`to_string` also renders Unicode (``µF / cm²``) and LaTeX. **Defining your own** .. code-block:: python >>> import saiunit as u >>> cal = u.Unit.create(u.joule.dim, 'calorie', 'cal', factor=4.184) >>> cal / u.gram Unit("cal / g") Comparison and arithmetic treat a bare ``Unit`` operand differently. Comparing a ``Quantity`` against a bare ``Unit`` implicitly reads the unit as "one of that unit" (``1 * unit``), so ``Quantity(1, mV) == mV`` is ``True``. Addition/subtraction, by contrast, reject a bare ``Unit`` operand outright (``Quantity(1, mV) + mV`` raises ``TypeError``), since there is no natural mantissa to add. Both behaviours are intentional; see ``__eq__`` for the comparison side. Examples -------- Create a simple unit: .. code-block:: python >>> import saiunit as u >>> u.volt Unit("V") >>> u.mvolt Unit("mV") Combine units: .. code-block:: python >>> import saiunit as u >>> u.volt / u.amp Unit("V / A") """ __module__ = "saiunit" __slots__ = ["_dim", "_base", "_scale", "_factor", "_terms", "_pre", "_name", "_hash", "_disp", "_str"] __array_priority__ = 1000 _dim: 'Dimension' _base: int | float _scale: int | float _factor: int | float # Canonical ``((Atom, exponent), ...)`` display terms and the numeric # ``(scale, factor)`` prefactor; ``scale``/``factor`` are derived from # them. ``_terms`` is None only when scale or factor is a JAX tracer. _terms: 'Terms | None' _pre: 'Pre' # Explicit full name of a named unit or power alias; None for composites. _name: str | None _hash: int | None _disp: 'tuple[Terms, Pre] | None' _str: str | None def __init__( self, dim: 'Dimension | str | None' = None, scale: int | float = 0, base: int | float = 10., factor: int | float = 1., name: str | None = None, dispname: str | None = None, is_fullname: bool = True, display_parts=None, ): # String-based construction: Unit("mV"), Unit("J / kg"), etc. if isinstance(dim, str): # The string form ignores every other constructor argument — # silently dropping ``Unit("mV", scale=99, factor=99)`` was a # source of confusing bugs. Reject any non-default secondary # argument explicitly so the caller knows. extras = [] if scale != 0: extras.append("scale") if base != 10.: extras.append("base") if factor != 1.: extras.append("factor") if name is not None: extras.append("name") if dispname is not None: extras.append("dispname") if is_fullname is not True: extras.append("is_fullname") if display_parts is not None: extras.append("display_parts") if extras: raise TypeError( "Unit(str, ...) does not accept additional arguments: " + ", ".join(extras) + ". Use parse_unit() and modify the result, or construct " "the Unit from a Dimension instead." ) self._assign(parse_unit(dim)) return # ``base`` is fixed at 10 for now — Units canonicalize to base=10 # internally, and accepting other bases silently rewrote them, # losing information. Raise so callers can not be surprised. if base != 10.: raise ValueError( f"Unit currently only supports base=10; got base={base!r}. " "Encode non-decimal scales in ``factor`` instead." ) scale = _normalise_scalar(scale) factor = _normalise_scalar(factor) _validate_scale_and_factor(scale, factor) # The physical unit dimensions of this unit if dim is None: dim = DIMENSIONLESS if not isinstance(dim, Dimension): raise TypeError(f'Expected instance of Dimension, but got {dim}') if not (isinstance(scale, (int, float)) and isinstance(factor, (int, float))): # JAX tracer scale/factor: no symbolic display terms. self._assign(Unit._make(dim, scale, factor, None, PRE_ONE)) elif display_parts is not None: self._assign(_from_legacy(dim, scale, factor, name, dispname, is_fullname, display_parts)) elif name is not None and is_fullname: self._assign(_named_unit(dim, scale, factor, name, dispname if dispname is not None else name)) else: self._assign(_anonymous_unit(dim, scale, factor)) @classmethod def _make( cls, dim: Dimension, scale: Any, factor: Any, terms: 'Terms | None', pre: 'Pre', name: str | None = None, ) -> 'Unit': """Construct a Unit from already-validated fields (fast path).""" u = object.__new__(cls) u._dim = dim u._base = 10. u._scale = scale u._factor = factor u._terms = terms u._pre = pre u._name = name u._hash = None u._disp = None u._str = None return u def _assign(self, other: 'Unit') -> None: self._dim = other._dim self._base = other._base self._scale = other._scale self._factor = other._factor self._terms = other._terms self._pre = other._pre self._name = other._name self._hash = None self._disp = other._disp self._str = other._str def _single_atom(self) -> 'Atom | None': """The atom of a plain named unit (one atom, exponent 1, no prefactor).""" terms = self._terms if terms is not None and len(terms) == 1 and terms[0][1] == 1 and self._pre == PRE_ONE: return terms[0][0] return None @property def factor(self) -> float: """ Return the conversion factor of the unit. The factor represents a multiplicative constant that converts a quantity expressed in this unit to its base-unit equivalent. For example, 1 calorie = 4.184 joule, so ``calorie.factor == 4.184``. Returns ------- float The conversion factor. Examples -------- .. code-block:: python >>> import saiunit as u >>> u.volt.factor 1.0 """ return self._factor @factor.setter def factor(self, factor): raise NotImplementedError( "Cannot set the factor of a Unit object directly," "Please create a new Unit object with the factor you want." ) @property def base(self) -> float: """ Return the base of the unit's scale exponent. The base is the number that is raised to the ``scale`` power to produce the unit's magnitude. For SI-prefixed units this is 10 (e.g. ``kilo`` means ``10 ** 3``). Returns ------- float The base of the exponent. Examples -------- .. code-block:: python >>> import saiunit as u >>> u.kvolt.base 10.0 """ return self._base @base.setter def base(self, base): raise NotImplementedError( "Cannot set the base of a Unit object directly," "Please create a new Unit object with the base you want." ) @property def scale(self) -> float | int: """ Return the scale exponent of the unit. The scale is the integer exponent applied to :attr:`base` to produce the unit's magnitude relative to the base unit. For example, ``mvolt`` has ``scale == -3`` (i.e. ``10 ** -3``). Returns ------- float or int The scale exponent. Examples -------- .. code-block:: python >>> import saiunit as u >>> u.mvolt.scale -3 """ return self._scale @scale.setter def scale(self, scale): raise NotImplementedError( "Cannot set the scale of a Unit object directly," "Please create a new Unit object with the scale you want." ) @property def magnitude(self) -> float: """ Return the absolute magnitude of the unit. The magnitude is computed as ``factor * base ** scale`` and represents the overall multiplicative factor that converts a value in this unit to the corresponding base-unit value. Returns ------- float The absolute magnitude of the unit. Extreme scales whose magnitude exceeds the float range yield ``inf`` (IEEE-754 overflow semantics) rather than raising. Examples -------- .. code-block:: python >>> import saiunit as u >>> u.mvolt.magnitude 0.001 >>> u.kvolt.magnitude 1000.0 """ # magnitude = factor * base ** scale try: return self.factor * self.base ** self.scale except OverflowError: # Python float pow raises on overflow instead of following # IEEE-754; treat extreme scales as infinity like every other # float operation in the library. return float('inf') @magnitude.setter def magnitude(self, scale): raise NotImplementedError( "Cannot set the magnitude of a Unit object." ) @property def dim(self) -> Dimension: """ Return the physical unit dimensions of this unit. Returns ------- Dimension The :class:`~saiunit.Dimension` instance describing the physical dimensions (e.g. length, mass, time, ...). Examples -------- .. code-block:: python >>> import saiunit as u >>> u.volt.dim metre ** 2 * kilogram * second ** -3 * amp ** -1 """ return self._dim @dim.setter def dim(self, value): # Do not support setting the unit directly raise NotImplementedError( "Cannot set the dimension of a Quantity object directly," "Please create a new Quantity object with the dimension you want." ) @property def is_unitless(self) -> bool: """ Whether the unit is dimensionless with no scaling. A unit is considered unitless when its dimension is dimensionless, its scale exponent is 0, and its factor is 1.0. Returns ------- bool ``True`` if the unit is unitless, ``False`` otherwise. Examples -------- .. code-block:: python >>> import saiunit as u >>> u.UNITLESS.is_unitless True >>> u.volt.is_unitless False """ return self.dim.is_dimensionless and self.scale == 0 and self.factor == 1.0 @property def should_display_unit(self) -> bool: """ Whether the unit should be shown in formatted output. Returns ``True`` unless the unit renders as ``"1"``: dimensionless units that carry a meaningful name (e.g. radian, steradian) or a scale (``mV / V``) are shown. Returns ------- bool ``True`` if the unit should be displayed, ``False`` otherwise. Examples -------- .. code-block:: python >>> import saiunit as u >>> u.volt.should_display_unit True >>> u.UNITLESS.should_display_unit False """ return str(self) != '1' @property def is_fullname(self) -> bool: """Whether this is a named unit (or power alias) rather than a composite.""" return self._name is not None @property def name(self): """ Return the full name of the unit. For composite units this is the canonical display string. Returns ------- str The full name of the unit (e.g. ``'volt'``, ``'mvolt'``). Examples -------- .. code-block:: python >>> import saiunit as u >>> u.volt.name 'volt' >>> u.mvolt.name 'mvolt' """ return self._name if self._name is not None else str(self) @name.setter def name(self, name): raise NotImplementedError( "Cannot set the name of a Unit object directly," "Please create a new Unit object with the name you want." ) @property def dispname(self): """ Return the display name of the unit. The display name is the canonical string used when rendering the unit (e.g. ``'V'`` for volt, ``'mV'`` for millivolt), identical to ``str(unit)``. Returns ------- str The display name of the unit. Examples -------- .. code-block:: python >>> import saiunit as u >>> u.volt.dispname 'V' >>> u.mvolt.dispname 'mV' """ return str(self) @dispname.setter def dispname(self, dispname): raise NotImplementedError( "Cannot set the dispname of a Unit object directly," "Please create a new Unit object with the dispname you want." )
[docs] def factorless(self) -> 'Unit': """ Return an equivalent Unit with the factor set to 1. If this unit already has ``factor == 1``, the unit itself is returned unchanged. (Substituting a registry-preferred alias here would silently rename units, e.g. becquerel → hertz or steradian → radian.) Returns ------- Unit This unit if its factor is already 1, otherwise a Unit with the factor set to 1 (the registered standard unit for the same dimension/scale when one exists). Notes ----- For a dimensionless unit, the result may carry an angular label (e.g. ``rad``) even though the input was a plain ratio: saiunit does not distinguish angle from ratio in the dimensionless registry keyspace. Examples -------- .. code-block:: python >>> import saiunit as u >>> pound = u.Unit.create( ... u.get_or_create_dimension(kg=1), 'pound', 'lb', factor=0.453592) >>> pound.factor 0.453592 >>> pound.factorless().factor 1.0 """ # Already factorless — nothing to strip. if isinstance(self.factor, (int, float)) and self.factor == 1.: return self # using standard units key = (self.dim, self.scale, self.base, 1.) if key in _standard_units: candidate = _standard_units[key] # Dimensionless keys collapse radian powers (rad^2, rad^3, ...) # onto plain ratio scales; substituting a power alias would # mislabel a first-power unit (arcmin -> "crad^2"). Only # accept plain named units for dimensionless dims. if not self.dim.is_dimensionless or candidate._single_atom() is not None: return candidate # using temporary units return Unit(dim=self.dim, scale=self.scale, base=self.base)
[docs] def simplify(self) -> 'Unit': """ Return the registered unit with exactly this unit's value, if any. Unit arithmetic only collapses onto a curated set of units (``kg * m / s^2`` displays as ``N``, but ``V * s`` stays ``V * s``). ``simplify`` collapses onto any registered unit, e.g. ``V * s`` → ``Wb`` and ``mol / l`` → ``M``. Dimensionless units, and units with no registered match, become an anonymous unit (``mV / V`` → ``10^-3``). Returns ------- Unit A unit equal to this one. Examples -------- .. code-block:: python >>> import saiunit as u >>> (u.volt * u.second).simplify() Unit("Wb") >>> (u.mvolt / u.volt).simplify() Unit("10^-3") """ if self._terms is None: return self if not self.dim.is_dimensionless: unit = _standard_units.get((self.dim, self.scale, self.base, self.factor)) if unit is not None: return unit return _anonymous_unit(self.dim, self.scale, self.factor)
[docs] def copy(self): """ Return a copy of this Unit. Returns ------- Unit A new Unit object with the same attributes. Examples -------- .. code-block:: python >>> import saiunit as u >>> v = u.volt.copy() >>> v == u.volt True >>> v is u.volt False """ return Unit._make(self._dim, self._scale, self._factor, self._terms, self._pre, self._name)
def __deepcopy__(self, memodict): return self.copy() def __hash__(self): if self._hash is None: # Equality is *physical*: two units that resolve to the same # ``(dim, factor, base, scale)`` must hash equal regardless # of name spelling (e.g. ``metre`` vs ``meter``). self._hash = hash( ( self.dim, self.factor, self.base, self.scale, ) ) return self._hash
[docs] def has_same_magnitude(self, other: 'Unit') -> bool: """ Whether this Unit has the same magnitude as another Unit. Two units have the same magnitude when they share the same ``scale``, ``base``, and ``factor``. Note that the comparison is component-wise, not on the computed product ``factor * base**scale``: a unit encoded as ``scale=3`` and one encoded as ``factor=1000.`` have equal magnitude products but compare unequal here. Note also that comparing quantities across factor units after conversion is exact-float equality: e.g. ``1*u.inch == 25.4*u.mm`` is ``False`` (the conversion ratio is off by one ulp). For factor units, prefer ``u.math.isclose`` over ``==``. Parameters ---------- other : Unit The other Unit to compare with. Returns ------- bool Whether the two Units have the same magnitude. Examples -------- .. code-block:: python >>> import saiunit as u >>> u.mvolt.has_same_magnitude(u.mamp) True >>> u.mvolt.has_same_magnitude(u.volt) False """ return self.scale == other.scale and self.base == other.base and self.factor == other.factor
[docs] def has_same_base(self, other: 'Unit') -> bool: """ Whether this Unit has the same ``base`` as another Unit. Parameters ---------- other : Unit The other Unit to compare with. Returns ------- bool Whether the two Units have the same base. Examples -------- .. code-block:: python >>> import saiunit as u >>> u.volt.has_same_base(u.amp) True >>> u.volt.has_same_base(u.mvolt) True """ return self.base == other.base
[docs] def has_same_dim(self, other: 'Unit') -> bool: """ Whether this Unit has the same unit dimensions as another Unit. Parameters ---------- other : Unit The other Unit to compare with. Returns ------- bool Whether the two Units have the same unit dimensions. Examples -------- .. code-block:: python >>> import saiunit as u >>> u.volt.has_same_dim(u.mvolt) True >>> u.volt.has_same_dim(u.amp) False """ from ._base_getters import get_dim other_dim = get_dim(other) return get_dim(self) == other_dim
[docs] @staticmethod def create( dim: Dimension, name: str, dispname: str, scale: int | float = 0, base: float = 10., factor: float = 1., *, auto_simplify: bool = False, unicode: str | None = None, latex: str | None = None, ) -> 'Unit': """ Create and register a new named unit. Parameters ---------- dim : Dimension The dimensions of the unit. name : `str` The full name of the unit, e.g. ``'volt'`` dispname : `str` The ASCII display symbol, e.g. ``'V'``. A symbol of the form ``'<registered symbol>^<int>'`` (e.g. ``'cm^2'``) creates a power alias equivalent to :meth:`create_power`. scale : int, optional The scale of this unit as an exponent of 10, e.g. -3 for a unit that is 1/1000 of the base scale. Defaults to 0 (i.e. a base unit). base: float, optional The base for this unit (as the base of the exponent). Must be 10, the only supported base; other values raise ``ValueError``. factor: float, optional The factor for this unit (as the conversion factor), e.g. a factor of 1 cal = 4.18400 J, where 4.18400 is the factor. Defaults to 1. auto_simplify : bool, optional Display arithmetic results with exactly this unit's dimension and magnitude as this unit. Defaults to False. unicode : str, optional Unicode symbol (e.g. ``'Ω'``), used by ``to_string('unicode')`` and accepted by the parser. Defaults to ``dispname``. latex : str, optional LaTeX symbol (e.g. ``r'\\Omega'``). Defaults to ``\\mathrm{dispname}``. Returns ------- u : Unit The new unit. Examples -------- .. code-block:: python >>> import saiunit as u >>> from saiunit import Dimension >>> energy_dim = u.joule.dim >>> cal = u.Unit.create(energy_dim, 'calorie', 'cal', factor=4.184) >>> cal Unit("cal") """ if base != 10.: raise ValueError( f"Unit currently only supports base=10; got base={base!r}. " "Encode non-decimal scales in ``factor`` instead." ) scale = _normalise_scalar(scale) factor = _normalise_scalar(factor) _validate_scale_and_factor(scale, factor) u = _power_alias(dim, scale, factor, name, dispname) if u is None: u = _named_unit(dim, scale, factor, name, dispname, unicode=unicode, latex=latex) add_standard_unit(u, auto_simplify=auto_simplify) return u
[docs] @staticmethod def create_power(baseunit: 'Unit', n: int, name: str | None = None) -> 'Unit': """ Create and register a power alias such as ``cmetre2 = cm^2``. Parameters ---------- baseunit : Unit The unit to raise to a power. n : int The exponent. name : str, optional The full name; defaults to ``baseunit.name + str(n)``. Returns ------- Unit A unit equal to ``baseunit ** n`` that displays as ``'cm^2'`` and is registered under *name*. Examples -------- .. code-block:: python >>> import saiunit as u >>> cm2 = u.Unit.create_power(u.cmetre, 2) >>> cm2.name, str(cm2) ('cmetre2', 'cm^2') """ p = baseunit ** n u = Unit._make(p._dim, p._scale, p._factor, p._terms, p._pre, name if name is not None else f"{baseunit.name}{n}") add_standard_unit(u) return u
[docs] @staticmethod def create_scaled_unit(baseunit: 'Unit', scalefactor: str) -> 'Unit': """ Create a scaled unit from a base unit. The scaled unit inherits the Unicode/LaTeX symbols of the base unit (``kohm`` renders ``kΩ``) and, except for the ``da``, ``h``, ``d`` and ``c`` prefixes, its ``auto_simplify`` flag. Parameters ---------- baseunit : `Unit` The unit of which to create a scaled version, e.g. ``volt``, ``amp``. scalefactor : `str` The scaling factor, e.g. ``"m"`` for mvolt, mamp Returns ------- u : Unit The new unit. Examples -------- .. code-block:: python >>> import saiunit as u >>> uvolt = u.Unit.create_scaled_unit(u.volt, 'u') >>> uvolt.name 'uvolt' >>> uvolt.scale -6 """ if scalefactor not in _siprefixes: raise ValueError( f"Unknown SI prefix {scalefactor!r}. " f"Valid prefixes are: {list(_siprefixes.keys())}" ) name = scalefactor + baseunit.name scale = _siprefixes[scalefactor] + baseunit.scale base_atom = baseunit._single_atom() if base_atom is None: u = _named_unit(baseunit.dim, scale, baseunit.factor, name, scalefactor + baseunit.dispname) auto = False else: if scalefactor == '': unicode, latex = base_atom.unicode, base_atom.latex else: micro = scalefactor == 'u' unicode = ('µ' if micro else scalefactor) + base_atom.unicode if base_atom.latex == latex_mathrm(base_atom.symbol): latex = (r'\mu' if micro else '') + latex_mathrm( base_atom.symbol if micro else scalefactor + base_atom.symbol) else: latex = (r'\mu ' if micro else latex_mathrm(scalefactor)) + base_atom.latex u = _named_unit(baseunit.dim, scale, baseunit.factor, name, scalefactor + base_atom.symbol, unicode=unicode, latex=latex, prefix=scalefactor or None) auto = base_atom in _auto_atoms and scalefactor not in ('da', 'h', 'd', 'c') add_standard_unit(u, auto_simplify=auto) return u
def _display(self) -> 'tuple[Terms, Pre]': """Return the ``(terms, prefactor)`` to render (cached). * Dimensionless units of magnitude 1 show only their named dimensionless atoms (``rad``, ``sr``) — or ``1``. Other dimensionless units show every term (``mV / V``, ``h / ms``). * Dimensioned units containing a dimensionless atom keep their terms (``rad / s``, ``m * rad``). * A single plain atom shows itself. * Otherwise collapse onto the unique ``auto_simplify`` target with the same dimension and magnitude (``kg * m / s^2`` → ``N``), or with the same magnitude apart from the prefactor (``2 * V``); failing that, show the terms. """ disp = self._disp if disp is not None: return disp terms, pre = self._terms, self._pre assert terms is not None if self._dim.is_dimensionless: if self._scale == 0 and self._factor == 1: named = tuple(t for t in terms if t[0].dim.is_dimensionless) disp = (named, PRE_ONE) if named and derive_magnitude(named, PRE_ONE) == (0, 1) else ((), PRE_ONE) else: disp = (terms, pre) elif ( any(t[0].dim.is_dimensionless for t in terms) or (len(terms) == 1 and terms[0][1] == 1 and pre == PRE_ONE) ): disp = (terms, pre) else: disp = (terms, pre) targets = _auto_targets.get((self._dim, self._scale, self._base, self._factor)) if targets is not None and len(targets) == 1: disp = (((targets[0], 1),), PRE_ONE) elif pre != PRE_ONE: scale, factor = derive_magnitude(terms, PRE_ONE) targets = _auto_targets.get((self._dim, scale, self._base, factor)) if targets is not None and len(targets) == 1: disp = (((targets[0], 1),), pre) self._disp = disp return disp def _traced_str(self) -> str: """Display string of a unit whose scale or factor is a JAX tracer.""" terms = _si_terms(self.dim) dim_str = render(terms, PRE_ONE) if terms else '' pre_str = f'{self.factor} * {self.base}^{self.scale}' return f'{pre_str} * {dim_str}' if dim_str else pre_str
[docs] def to_string(self, format: str = 'ascii') -> str: """ Render the unit as a string. Parameters ---------- format : str One of ``'ascii'`` (canonical, parseable: ``mS * nA / cm^2``), ``'ascii_inline'`` (``mS * nA * cm^-2``), ``'unicode'`` (``mS·nA / cm²``), ``'unicode_inline'`` (``mS·nA·cm⁻²``), ``'latex'`` (``\\frac{\\mathrm{mS}\\,\\mathrm{nA}}{\\mathrm{cm}^{2}}``) or ``'latex_inline'``. Returns ------- str Examples -------- .. code-block:: python >>> import saiunit as u >>> (u.uF / u.cm ** 2).to_string('unicode') 'µF / cm²' >>> u.kohm.to_string('latex') '\\\\mathrm{k}\\\\Omega' """ if format == 'ascii': return str(self) if format not in STYLES: raise ValueError(f"Unknown unit format {format!r}; expected one of {STYLES}.") if self._terms is None: return self._traced_str() return render(*self._display(), format)
def __format__(self, format_spec: str) -> str: return self.to_string(format_spec or 'ascii') def _repr_latex_(self) -> str: return f"${self.to_string('latex')}$" def __repr__(self) -> str: return f"Unit(\"{self}\")" def __str__(self) -> str: s = self._str if s is None: s = self._traced_str() if self._terms is None else render(*self._display()) self._str = s return s def __mul__(self, other) -> 'Unit | Quantity': # self * other if isinstance(other, Unit): _assert_same_base(self, other) return _compose(self, 1, other, 1) elif isinstance(other, Dimension): raise TypeError(f"unit {self} cannot multiply by a Dimension {other}.") else: from ._base_quantity import Quantity if isinstance(other, Quantity): return Quantity(other.mantissa, unit=(self * other.unit)) # type: ignore[arg-type] return Quantity(other, unit=self) def __rmul__(self, other) -> 'Unit | Quantity': # other * self if isinstance(other, Unit): return other.__mul__(self) from ._base_quantity import Quantity if isinstance(other, Quantity): return Quantity(other.mantissa, unit=(other.unit * self)) # type: ignore[arg-type] return Quantity(other, unit=self) def __imul__(self, other): raise NotImplementedError("Units cannot be modified in-place") def __div__(self, other) -> 'Unit | Quantity': # self / other if isinstance(other, Unit): _assert_same_base(self, other) return _compose(self, 1, other, -1) elif isinstance(other, Dimension): raise TypeError(f"unit {self} cannot divide by a Dimension {other}.") else: # Mirror ``__mul__``: dividing a unit by a number or quantity # yields a Quantity (e.g. ``mV / 2`` == 0.5 mV), keeping the # operator surface consistent with ``mV * 2`` and ``2 / mV``. from ._base_quantity import Quantity if isinstance(other, Quantity): return Quantity(1.0 / other.mantissa, unit=(self / other.unit)) return Quantity(1.0 / other, unit=self) def __rdiv__(self, other) -> 'Unit | Quantity': # other / self if isinstance(other, Unit): return other.__div__(self) from ._base_quantity import Quantity if isinstance(other, Quantity): return Quantity(other.mantissa, unit=(other.unit / self)) return Quantity(other, unit=self.reverse())
[docs] def reverse(self): """ Return the multiplicative inverse of this unit. Computes ``1 / self``, producing a new unit with negated scale, inverted factor, and reciprocal dimensions. ``u.reverse().reverse()`` equals ``u`` exactly. Returns ------- Unit A new Unit representing the reciprocal of this unit. Examples -------- .. code-block:: python >>> import saiunit as u >>> u.second.reverse() Unit("Hz") >>> u.metre.reverse() Unit("1 / m") """ return _compose(self, -1)
def __idiv__(self, other): raise NotImplementedError("Units cannot be modified in-place") def __truediv__(self, oc): # self / oc return self.__div__(oc) def __rtruediv__(self, oc): # oc / self return self.__rdiv__(oc) def __itruediv__(self, other): raise NotImplementedError("Units cannot be modified in-place") def __floordiv__(self, oc): raise NotImplementedError("Units cannot be performed floor division") def __rfloordiv__(self, oc): raise NotImplementedError("Units cannot be performed floor division") def __ifloordiv__(self, other): raise NotImplementedError("Units cannot be modified in-place") def __pow__(self, other): # self ** other from ._base_getters import is_scalar_type if is_scalar_type(other): return _compose(self, norm_exp(_normalise_scalar(other))) else: raise TypeError( f"unit cannot perform an exponentiation (unit ** other) with a non-scalar, " f"since one unit cannot contain multiple units. \n" f"But we got unit={self}, other={other}" ) def __ipow__(self, other, modulo=None): raise NotImplementedError("Units cannot be modified in-place") def __add__(self, other): raise TypeError( "Units cannot be added: addition is defined on quantities, not units. " "To add quantities, attach mantissas first (e.g. 1*ms + 2*ms)." ) def __radd__(self, other): raise TypeError( "Units cannot be added: addition is defined on quantities, not units. " "To add quantities, attach mantissas first (e.g. 1*ms + 2*ms)." ) def __iadd__(self, other): raise NotImplementedError("Units cannot be modified in-place") def __sub__(self, other): raise TypeError( "Units cannot be subtracted: subtraction is defined on quantities, not " "units. To subtract quantities, attach mantissas first (e.g. 2*ms - 1*ms)." ) def __rsub__(self, other): raise TypeError( "Units cannot be subtracted: subtraction is defined on quantities, not " "units. To subtract quantities, attach mantissas first (e.g. 2*ms - 1*ms)." ) def __isub__(self, other): raise NotImplementedError("Units cannot be modified in-place") def __mod__(self, oc): raise NotImplementedError("Units cannot be performed modulo") def __rmod__(self, oc): raise NotImplementedError("Units cannot be performed modulo") def __imod__(self, other): raise NotImplementedError("Units cannot be modified in-place") def __eq__(self, other) -> bool: # Two Units are equal when they have the same dim/scale/base/factor # *components*. Names and display strings are not part of equality: # spelling aliases such as ``metre`` vs ``meter`` and # registry-canonical compounds such as ``A * ohm`` vs ``V`` compare # equal, and the corresponding hashes collide as required by the # ``__hash__`` contract. Note the comparison is component-wise, # not magnitude-based: ``Unit(scale=3)`` and ``Unit(factor=1000.)`` # have the same magnitude but compare unequal. Factor-1 # dimensionless units (radian, steradian) compare equal to # ``UNITLESS`` — physically they are 1. # # Non-Unit operands return ``NotImplemented`` so that the other # operand's reflected comparison runs (e.g. Quantity.__eq__), # keeping ``unit == quantity`` and ``quantity == unit`` symmetric. if not isinstance(other, Unit): return NotImplemented return ( (other.dim == self.dim) and (other.scale == self.scale) and (other.base == self.base) and (other.factor == self.factor) ) def __ne__(self, other) -> bool: result = self.__eq__(other) if result is NotImplemented: return result return not result def __abs__(self) -> 'Unit': """Return the unit itself — units are always non-negative.""" return self def __reduce__(self): # For pickling. The display terms are pickled with the unit so # composites (e.g. ``mS * nA / cm^2``) keep their rendering. return ( _to_unit_v2, (self._dim, self._scale, self._factor, self._terms, self._pre, self._name), ) def _to_unit_v2(dim, scale, factor, terms, pre, name): """Private pickle reconstruction shim for Unit.""" return Unit._make(dim, scale, factor, terms, pre, name) def _to_unit(dim, scale, base, factor, name, dispname, is_fullname, display_parts=None): """Reconstruct a Unit pickled by older saiunit versions (string display parts).""" return Unit( dim=dim, scale=scale, base=base, factor=factor, name=name, dispname=dispname, is_fullname=is_fullname, display_parts=display_parts if display_parts is not None else [], ) _to_unit_v2.__module__ = 'saiunit._base_unit' _to_unit.__module__ = 'saiunit._base_unit' # The seven SI base atoms; anonymous units (``Unit(dim)``) are displayed in # terms of them. They are interned, so ``metre``/``kilogram``/... defined # in ``_unit_common`` share these atoms. _SI_BASE_ATOMS = tuple( make_atom(symbol, name, get_or_create_dimension(**{symbol: 1}), 0, 1.) for symbol, name in ( ('m', 'metre'), ('kg', 'kilogram'), ('s', 'second'), ('A', 'amp'), ('K', 'kelvin'), ('mol', 'mole'), ('cd', 'candle'), ) ) def _si_terms(dim: Dimension) -> 'Terms': return combine_terms( tuple((atom, norm_exp(d)) for atom, d in zip(_SI_BASE_ATOMS, dim._dims.tolist()) if d), 1 ) def _anonymous_unit(dim: Dimension, scale: Any, factor: Any) -> Unit: """A unit with no name, displayed via SI base atoms (or an auto target).""" return Unit._make(dim, scale, factor, _si_terms(dim), (scale, factor)) def _named_unit( dim: Dimension, scale: Any, factor: Any, name: str, symbol: str, unicode: str | None = None, latex: str | None = None, prefix: str | None = None, ) -> Unit: atom = make_atom(symbol, name, dim, scale, factor, unicode=unicode, latex=latex, prefix=prefix) return Unit._make(dim, scale, factor, ((atom, 1),), PRE_ONE, name) def _power_alias(dim: Dimension, scale: Any, factor: Any, name: str, dispname: str) -> 'Unit | None': """Interpret a legacy ``'<symbol>^<int>'`` display name as a power alias.""" base_symbol, sep, exp = dispname.rpartition('^') if not sep or not exp.lstrip('-').isdigit(): return None base = _lookup_symbol(base_symbol) if base is None or base._single_atom() is None: return None p = base ** int(exp) if not (p.dim == dim and p.scale == scale and p.factor == factor): return None return Unit._make(p._dim, p._scale, p._factor, p._terms, p._pre, name) def _compose(a: Unit, ea: 'Exp', b: 'Unit | None' = None, eb: 'Exp' = 0) -> Unit: """Return ``a ** ea * b ** eb``: the single composition primitive.""" tb: 'Terms | None' = () if b is None else b._terms if a._terms is None or tb is None: return _compose_traced(a, ea, b, eb) terms = combine_terms(a._terms, ea, tb, eb) pre = _pre_pow(a._pre, ea) if b is not None and b._pre != PRE_ONE: pb = _pre_pow(b._pre, eb) pre = (pre[0] + pb[0], pre[1] * pb[1]) scale, factor = derive_magnitude(terms, pre) if type(ea) is int and type(eb) is int: dim = a._dim if ea == 1 else _dim_pow(a._dim, ea) if b is not None: dim = dim * b._dim if eb == 1 else (dim / b._dim if eb == -1 else dim * _dim_pow(b._dim, eb)) else: dim = derive_dim(terms) return Unit._make(dim, scale, factor, terms, pre) def _dim_pow(dim: Dimension, e: Any) -> Dimension: return dim ** e def _pre_pow(pre: 'Pre', e: 'Exp') -> 'Pre': if e == 1 or pre == PRE_ONE: return pre scale, factor = norm_scale(pre[0] * e), pre[1] if factor != 1: try: factor = factor ** (e if type(e) is int else float(e)) except OverflowError: raise ValueError( f"unit factor {factor} ** {e} overflows the float range; reduce the exponent." ) from None return (scale, factor) def _compose_traced(a: Unit, ea: 'Exp', b: 'Unit | None', eb: 'Exp') -> Unit: """Composition when a scale or factor is a JAX tracer (no display terms).""" fa = ea if type(ea) is int else float(ea) dim, scale, factor = _dim_pow(a.dim, fa), a.scale * fa, a.factor ** fa if b is not None: fb = eb if type(eb) is int else float(eb) dim, scale, factor = dim * _dim_pow(b.dim, fb), scale + b.scale * fb, factor * b.factor ** fb return Unit._make(dim, scale, factor, None, PRE_ONE) def _same_value(u: Unit, dim: Dimension, scale: Any, factor: Any) -> bool: return u.dim == dim and u.scale == scale and u.factor == factor def _from_legacy(dim, scale, factor, name, dispname, is_fullname, display_parts) -> Unit: """Build a Unit from the pre-0.4 ``(name, dispname, display_parts)`` fields. The display is recovered from the registry (by name, then dispname), then from the legacy display parts, then by parsing the display name. The given ``dim``/``scale``/``factor`` are authoritative: a candidate whose value differs is rejected. """ if is_fullname: for s in (name, dispname): if isinstance(s, str) and s: unit = _lookup_symbol(s) if unit is not None and _same_value(unit, dim, scale, factor): return unit candidates = [] if display_parts: try: unit = UNITLESS for part_name, part_disp, exp in display_parts: part = _lookup_symbol(part_name) or _lookup_symbol(part_disp) or parse_unit(part_disp) unit = unit * part ** exp candidates.append(unit) except (ValueError, TypeError): pass if isinstance(dispname, str) and dispname: try: candidates.append(parse_unit(dispname)) except (ValueError, TypeError): pass for unit in candidates: if _same_value(unit, dim, scale, factor): return unit if is_fullname and isinstance(name, str) and name: return _named_unit(dim, scale, factor, name, dispname if isinstance(dispname, str) and dispname else name) return _anonymous_unit(dim, scale, factor) UNITLESS = Unit() """ The canonical unitless (dimensionless) unit. ``UNITLESS`` is a singleton-like :class:`Unit` with no physical dimensions, a scale of 0, a base of 10, and a factor of 1. It is returned by default when a :class:`Unit` is constructed with no arguments, and is used internally as the neutral element of unit arithmetic. .. code-block:: python >>> import saiunit as u >>> u.UNITLESS.is_unitless True >>> u.UNITLESS.dim.is_dimensionless True """