qnty 0.0.8__py3-none-any.whl → 0.1.0__py3-none-any.whl

qnty/units/prefixes.py

@@ -0,0 +1,203 @@
+"""
+SI Prefix System
+================
+
+Standard SI prefixes for unit multiplication/division.
+Provides systematic handling of metric prefixes like kilo-, milli-, micro-, etc.
+"""
+
+from dataclasses import dataclass
+from enum import Enum
+
+from ..constants.numerical import PREFIX_LOOKUP_MIN_TOLERANCE, PREFIX_LOOKUP_TOLERANCE
+
+
+@dataclass(frozen=True, slots=True)
+class SIPrefix:
+    """
+    Standard SI prefix definition.
+
+    Attributes:
+        name: Full prefix name (e.g., "kilo", "milli")
+        symbol: Standard symbol (e.g., "k", "m")
+        factor: Multiplication factor relative to base unit (e.g., 1000, 0.001)
+    """
+
+    name: str
+    symbol: str
+    factor: float
+
+    def apply_to_name(self, base_name: str) -> str:
+        """Apply prefix to a base unit name."""
+        return self.name + base_name if self.name else base_name
+
+    def apply_to_symbol(self, base_symbol: str) -> str:
+        """Apply prefix to a base unit symbol."""
+        return self.symbol + base_symbol if self.symbol else base_symbol
+
+
+class StandardPrefixes(Enum):
+    """
+    Standard SI prefixes with their multiplication factors.
+
+    From yotta (10^24) to yocto (10^-24).
+    """
+
+    # Larger prefixes (10^3 to 10^24)
+    YOTTA = SIPrefix("yotta", "Y", 1e24)
+    ZETTA = SIPrefix("zetta", "Z", 1e21)
+    EXA = SIPrefix("exa", "E", 1e18)
+    PETA = SIPrefix("peta", "P", 1e15)
+    TERA = SIPrefix("tera", "T", 1e12)
+    GIGA = SIPrefix("giga", "G", 1e9)
+    MEGA = SIPrefix("mega", "M", 1e6)
+    KILO = SIPrefix("kilo", "k", 1e3)
+    HECTO = SIPrefix("hecto", "h", 1e2)
+    DECA = SIPrefix("deca", "da", 1e1)
+
+    # Base (no prefix)
+    NONE = SIPrefix("", "", 1.0)
+
+    # Smaller prefixes (10^-1 to 10^-24)
+    DECI = SIPrefix("deci", "d", 1e-1)
+    CENTI = SIPrefix("centi", "c", 1e-2)
+    MILLI = SIPrefix("milli", "m", 1e-3)
+    MICRO = SIPrefix("micro", "μ", 1e-6)
+    NANO = SIPrefix("nano", "n", 1e-9)
+    PICO = SIPrefix("pico", "p", 1e-12)
+    FEMTO = SIPrefix("femto", "f", 1e-15)
+    ATTO = SIPrefix("atto", "a", 1e-18)
+    ZEPTO = SIPrefix("zepto", "z", 1e-21)
+    YOCTO = SIPrefix("yocto", "y", 1e-24)
+
+
+# Common prefix groups for different unit types
+COMMON_LENGTH_PREFIXES: list[StandardPrefixes] = [
+    StandardPrefixes.KILO,
+    StandardPrefixes.CENTI,
+    StandardPrefixes.MILLI,
+    StandardPrefixes.MICRO,
+    StandardPrefixes.NANO,
+]
+
+COMMON_MASS_PREFIXES: list[StandardPrefixes] = [
+    StandardPrefixes.KILO,  # Note: kilogram is the SI base unit
+    StandardPrefixes.MILLI,
+    StandardPrefixes.MICRO,
+]
+
+COMMON_TIME_PREFIXES: list[StandardPrefixes] = [
+    StandardPrefixes.MILLI,
+    StandardPrefixes.MICRO,
+    StandardPrefixes.NANO,
+    StandardPrefixes.PICO,
+]
+
+COMMON_ELECTRIC_PREFIXES: list[StandardPrefixes] = [
+    StandardPrefixes.KILO,
+    StandardPrefixes.MILLI,
+    StandardPrefixes.MICRO,
+    StandardPrefixes.NANO,
+    StandardPrefixes.PICO,
+]
+
+COMMON_ENERGY_PREFIXES: list[StandardPrefixes] = [
+    StandardPrefixes.KILO,
+    StandardPrefixes.MEGA,
+    StandardPrefixes.GIGA,
+]
+
+COMMON_POWER_PREFIXES: list[StandardPrefixes] = [
+    StandardPrefixes.KILO,
+    StandardPrefixes.MEGA,
+    StandardPrefixes.GIGA,
+    StandardPrefixes.MILLI,
+    StandardPrefixes.MICRO,
+]
+
+COMMON_PRESSURE_PREFIXES: list[StandardPrefixes] = [
+    StandardPrefixes.KILO,
+    StandardPrefixes.MEGA,
+    StandardPrefixes.GIGA,
+]
+
+
+# Lookup dictionaries for fast prefix searches
+_NAME_TO_PREFIX: dict[str, SIPrefix] = {}
+_SYMBOL_TO_PREFIX: dict[str, SIPrefix] = {}
+_FACTOR_TO_PREFIX: dict[float, SIPrefix] = {}
+
+
+def _initialize_lookup_caches() -> None:
+    """Initialize lookup caches for fast prefix lookups."""
+    for prefix_enum in StandardPrefixes:
+        prefix = prefix_enum.value
+        _NAME_TO_PREFIX[prefix.name] = prefix
+        _SYMBOL_TO_PREFIX[prefix.symbol] = prefix
+        _FACTOR_TO_PREFIX[prefix.factor] = prefix
+
+
+def get_prefix_by_name(name: str) -> SIPrefix | None:
+    """Get a prefix by its name (e.g., 'kilo', 'milli')."""
+    return _NAME_TO_PREFIX.get(name)
+
+
+def get_prefix_by_symbol(symbol: str) -> SIPrefix | None:
+    """Get a prefix by its symbol (e.g., 'k', 'm')."""
+    return _SYMBOL_TO_PREFIX.get(symbol)
+
+
+def get_prefix_by_factor(factor: float, tolerance: float = PREFIX_LOOKUP_TOLERANCE) -> SIPrefix | None:
+    """Get a prefix by its multiplication factor."""
+    # Check for exact match first
+    if factor in _FACTOR_TO_PREFIX:
+        return _FACTOR_TO_PREFIX[factor]
+
+    # Search with tolerance if meaningful
+    if tolerance > PREFIX_LOOKUP_MIN_TOLERANCE:
+        for cached_factor, prefix in _FACTOR_TO_PREFIX.items():
+            if abs(cached_factor - factor) < tolerance:
+                return prefix
+    return None
+
+
+def extract_prefix_values(prefix_enums: list[StandardPrefixes]) -> list[SIPrefix]:
+    """Extract SIPrefix values from StandardPrefixes enums."""
+    return [prefix_enum.value for prefix_enum in prefix_enums]
+
+
+# Units that should get automatic prefixes
+PREFIXABLE_UNITS: dict[str, list[StandardPrefixes]] = {
+    # Base SI units
+    "meter": COMMON_LENGTH_PREFIXES,
+    "gram": COMMON_MASS_PREFIXES,
+    "second": COMMON_TIME_PREFIXES,
+    "ampere": COMMON_ELECTRIC_PREFIXES,
+    "kelvin": [],  # Temperature usually doesn't use prefixes
+    "mole": [StandardPrefixes.MILLI, StandardPrefixes.MICRO],
+    "candela": [],  # Luminous intensity rarely uses prefixes
+    # Derived SI units
+    "pascal": COMMON_PRESSURE_PREFIXES,
+    "joule": COMMON_ENERGY_PREFIXES,
+    "watt": COMMON_POWER_PREFIXES,
+    "coulomb": COMMON_ELECTRIC_PREFIXES,
+    "volt": COMMON_ELECTRIC_PREFIXES,
+    "farad": [StandardPrefixes.MILLI, StandardPrefixes.MICRO, StandardPrefixes.NANO, StandardPrefixes.PICO],
+    "ohm": [StandardPrefixes.KILO, StandardPrefixes.MEGA, StandardPrefixes.MILLI],
+    "siemens": [StandardPrefixes.MILLI, StandardPrefixes.MICRO],
+    "weber": [StandardPrefixes.MILLI, StandardPrefixes.MICRO],
+    "tesla": [StandardPrefixes.MILLI, StandardPrefixes.MICRO, StandardPrefixes.NANO],
+    "henry": [StandardPrefixes.MILLI, StandardPrefixes.MICRO, StandardPrefixes.NANO],
+    "lumen": [],
+    "lux": [],
+    "becquerel": [StandardPrefixes.KILO, StandardPrefixes.MEGA, StandardPrefixes.GIGA],
+    "gray": [StandardPrefixes.MILLI, StandardPrefixes.MICRO],
+    "sievert": [StandardPrefixes.MILLI, StandardPrefixes.MICRO],
+    "hertz": [StandardPrefixes.KILO, StandardPrefixes.MEGA, StandardPrefixes.GIGA],
+    "newton": [StandardPrefixes.KILO, StandardPrefixes.MILLI],
+    "bar": [StandardPrefixes.MILLI],  # Common non-SI unit
+    "liter": [StandardPrefixes.MILLI, StandardPrefixes.MICRO],  # Common non-SI unit
+}
+
+# Initialize lookup caches on module load
+_initialize_lookup_caches()

qnty/{unit.py → units/registry.py}

@@ -7,23 +7,24 @@ Unit definitions, constants and registry for the high-performance unit system.
 
 from dataclasses import dataclass
 
-from .dimension import DimensionSignature
+from ..dimensions import DimensionSignature
 from .prefixes import SIPrefix, StandardPrefixes
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, slots=True)
 class UnitDefinition:
-    """Immutable unit definition optimized for performance."""
+    """Immutable unit definition for the unit system."""
+
     name: str
     symbol: str
     dimension: DimensionSignature
     si_factor: float
     si_offset: float = 0.0
     base_unit_name: str | None = None  # Base unit without prefix
-    prefix: SIPrefix | None = None      # SI prefix if applicable
-    
+    prefix: SIPrefix | None = None  # SI prefix if applicable
+
     @classmethod
-    def with_prefix(cls, base_def: 'UnitDefinition', prefix: SIPrefix) -> 'UnitDefinition':
+    def with_prefix(cls, base_def: "UnitDefinition", prefix: SIPrefix) -> "UnitDefinition":
         """Create a new unit definition with an SI prefix."""
         return cls(
             name=prefix.apply_to_name(base_def.name),
@@ -32,80 +33,82 @@ class UnitDefinition:
             si_factor=base_def.si_factor * prefix.factor,
             si_offset=base_def.si_offset,
             base_unit_name=base_def.name,
-            prefix=prefix
+            prefix=prefix,
         )
 
 
 class UnitConstant:
-    """Unit constant that provides type safety and performance."""
-    
+    """Unit constant that provides type safety."""
+
+    __slots__ = ("definition", "name", "symbol", "dimension", "si_factor", "_hash_cache")
+
     def __init__(self, definition: UnitDefinition):
         self.definition = definition
         self.name = definition.name
         self.symbol = definition.symbol
         self.dimension = definition.dimension
         self.si_factor = definition.si_factor
-    
-    def __str__(self):
+        self._hash_cache = hash(self.name)
+
+    def __str__(self) -> str:
         return self.symbol
-    
-    def __eq__(self, other):
-        """Fast equality check for unit constants."""
+
+    def __eq__(self, other) -> bool:
+        """Equality check for unit constants."""
         return isinstance(other, UnitConstant) and self.name == other.name
-    
-    def __hash__(self):
+
+    def __hash__(self) -> int:
         """Enable unit constants as dictionary keys."""
-        return hash(self.name)
+        return self._hash_cache
 
 
-class HighPerformanceRegistry:
-    """Ultra-fast registry with pre-computed conversion tables."""
-    
+class Registry:
+    """Unit registry with pre-computed conversion tables."""
+
+    __slots__ = ("units", "conversion_table", "dimensional_groups", "_finalized", "base_units", "prefixable_units", "_conversion_cache", "_dimension_cache")
+
     def __init__(self):
         self.units: dict[str, UnitDefinition] = {}
         self.conversion_table: dict[tuple[str, str], float] = {}  # (from_unit, to_unit) -> factor
         self.dimensional_groups: dict[int | float, list[UnitDefinition]] = {}
-        self._dimension_cache: dict[int | float, UnitConstant] = {}  # Cache for common dimension mappings
         self._finalized = False
         self.base_units: dict[str, UnitDefinition] = {}  # Track base units for prefix generation
         self.prefixable_units: set[str] = set()  # Track which units can have prefixes
+        # Cache for frequently used conversions
+        self._conversion_cache: dict[tuple[str, str], float] = {}
+        # Cache for common dimension mappings
+        self._dimension_cache: dict[int | float, UnitConstant] = {}
 
-        # Registry starts empty - units are registered via register_all_units() in __init__.py
-    
-    
-    def register_unit(self, unit_def: UnitDefinition):
+    def register_unit(self, unit_def: UnitDefinition) -> None:
         """Register a single unit definition."""
         if self._finalized:
             raise RuntimeError("Cannot register units after registry is finalized")
-            
+
         self.units[unit_def.name] = unit_def
-        
+
         # Group by dimension
         dim_sig = unit_def.dimension._signature
-        if dim_sig not in self.dimensional_groups:
-            self.dimensional_groups[dim_sig] = []
-        self.dimensional_groups[dim_sig].append(unit_def)
-    
-    def register_with_prefixes(
-            self,
-            unit_def: UnitDefinition,
-            prefixes: list[StandardPrefixes] | None = None
-        ):
+        if dim_sig in self.dimensional_groups:
+            self.dimensional_groups[dim_sig].append(unit_def)
+        else:
+            self.dimensional_groups[dim_sig] = [unit_def]
+
+    def register_with_prefixes(self, unit_def: UnitDefinition, prefixes: list[StandardPrefixes] | None = None) -> None:
         """
         Register a unit and automatically generate prefixed variants.
-        
+
         Args:
             unit_def: The base unit definition
             prefixes: List of StandardPrefixes enum values to apply. If None, uses common prefixes.
         """
         if self._finalized:
             raise RuntimeError("Cannot register units after registry is finalized")
-        
+
         # Register base unit
         self.register_unit(unit_def)
         self.base_units[unit_def.name] = unit_def
         self.prefixable_units.add(unit_def.name)
-        
+
         # Generate and register prefixed variants
         if prefixes:
             for prefix_enum in prefixes:
@@ -113,37 +116,62 @@ class HighPerformanceRegistry:
                 if prefix.name:  # Skip NONE prefix (empty name)
                     prefixed_unit = UnitDefinition.with_prefix(unit_def, prefix)
                     self.register_unit(prefixed_unit)
-    
-    def finalize_registration(self):
+
+    def finalize_registration(self) -> None:
         """Called after all units registered to precompute conversions."""
         if not self._finalized:
             self._precompute_conversions()
             self._finalized = True
 
-    def _precompute_conversions(self):
-        """Pre-compute all unit conversions for maximum speed."""
-        self.conversion_table.clear()  # Clear existing conversions
+    def _precompute_conversions(self) -> None:
+        """Pre-compute all unit conversions for fast lookup."""
+        self.conversion_table.clear()
+        self._conversion_cache.clear()
+
         for group in self.dimensional_groups.values():
+            if len(group) <= 1:
+                continue  # Skip groups with single units
+
+            # Compute conversion factors for all unit pairs
             for from_unit in group:
                 for to_unit in group:
                     if from_unit != to_unit:
                         factor = from_unit.si_factor / to_unit.si_factor
-                        key = (from_unit.name, to_unit.name)
-                        self.conversion_table[key] = factor
-    
+                        self.conversion_table[(from_unit.name, to_unit.name)] = factor
+
     def convert(self, value: float, from_unit: UnitConstant, to_unit: UnitConstant) -> float:
-        """Ultra-fast conversion using pre-computed table."""
-        if from_unit == to_unit:
+        """Convert a value between units with optimized lookups."""
+        # ULTRA-FAST PATH: Same unit - no conversion needed (most common case)
+        if from_unit.name == to_unit.name:
             return value
-        
-        # O(1) lookup for pre-computed conversions
-        key = (from_unit.name, to_unit.name)
-        if key in self.conversion_table:
-            return value * self.conversion_table[key]
-        
-        # Fallback (shouldn't happen for registered units)
-        return value * from_unit.si_factor / to_unit.si_factor
-
-
-# Global high-performance registry
-registry = HighPerformanceRegistry()
+
+        # OPTIMIZATION: Extract names once to avoid repeated attribute access
+        from_name = from_unit.name
+        to_name = to_unit.name
+        key = (from_name, to_name)
+
+        # STREAMLINED CACHE: Direct dictionary access with batched operations
+        conversion_cache = self._conversion_cache
+        if key in conversion_cache:
+            return value * conversion_cache[key]
+
+        # OPTIMIZED LOOKUP: Direct table access
+        conversion_table = self.conversion_table
+        if key in conversion_table:
+            factor = conversion_table[key]
+            # Cache frequently used conversions - direct assignment for speed
+            if len(conversion_cache) < 50:
+                conversion_cache[key] = factor
+            return value * factor
+
+        # FAST FALLBACK: Direct SI factor calculation with caching
+        from_si = from_unit.si_factor
+        to_si = to_unit.si_factor
+        factor = from_si / to_si
+        if len(conversion_cache) < 50:
+            conversion_cache[key] = factor
+        return value * factor
+
+
+# Global unit registry
+registry = Registry()

qnty/utils/__init__.py

@@ -0,0 +1,16 @@
+"""Shared utilities and helper functions."""
+
+from .protocols import ExpressionProtocol, TypeRegistry, VariableProtocol, is_expression, is_variable, register_expression_type, register_variable_type
+from .scope_discovery import ScopeDiscoveryService, discover_variables_from_scope
+
+__all__ = [
+    "ScopeDiscoveryService",
+    "discover_variables_from_scope",
+    "TypeRegistry",
+    "ExpressionProtocol",
+    "VariableProtocol",
+    "register_expression_type",
+    "register_variable_type",
+    "is_expression",
+    "is_variable",
+]

qnty/utils/caching/__init__.py

@@ -0,0 +1,23 @@
+"""
+Caching utilities for the qnty library.
+
+Provides centralized cache management for improved performance and memory efficiency.
+"""
+
+from .manager import (
+    CacheStats,
+    UnifiedCacheManager,
+    clear_all_caches,
+    get_cache_manager,
+    get_cache_statistics,
+    get_memory_usage,
+)
+
+__all__ = [
+    "UnifiedCacheManager",
+    "CacheStats",
+    "get_cache_manager",
+    "clear_all_caches",
+    "get_cache_statistics",
+    "get_memory_usage",
+]