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

qnty/units/prefixes.py

@@ -9,36 +9,40 @@ 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. Optimized for performance."""
-        return base_name if not self.name else self.name + base_name
-    
+        """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. Optimized for performance."""
-        return base_symbol if not self.symbol else self.symbol + base_symbol
+        """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)
@@ -50,10 +54,10 @@ class StandardPrefixes(Enum):
     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)
@@ -67,7 +71,7 @@ class StandardPrefixes(Enum):
     YOCTO = SIPrefix("yocto", "y", 1e-24)
 
 
-# Common prefix groups for different unit types - type annotated for better IDE support
+# Common prefix groups for different unit types
 COMMON_LENGTH_PREFIXES: list[StandardPrefixes] = [
     StandardPrefixes.KILO,
     StandardPrefixes.CENTI,
@@ -118,38 +122,39 @@ COMMON_PRESSURE_PREFIXES: list[StandardPrefixes] = [
 ]
 
 
-# Performance optimization: Pre-computed lookup dictionaries
+# 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():
-    """Initialize lookup caches for O(1) prefix lookups."""
+
+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'). O(1) lookup."""
+    """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'). O(1) lookup."""
+    """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 = 1e-10) -> SIPrefix | None:
-    """Get a prefix by its multiplication factor. O(1) lookup for exact matches, optimized tolerance search."""
-    # Fast path for exact matches
+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]
-    
-    # Optimized tolerance path - only search if tolerance is meaningful
-    if tolerance > 1e-15:  # Avoid expensive search for tiny tolerances
-        # Use items() view for better performance than .items()
+
+    # 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
@@ -157,94 +162,42 @@ def get_prefix_by_factor(factor: float, tolerance: float = 1e-10) -> SIPrefix |
 
 
 def extract_prefix_values(prefix_enums: list[StandardPrefixes]) -> list[SIPrefix]:
-    """Extract SIPrefix values from StandardPrefixes enums efficiently.
-    
-    This is optimized for bulk operations that need to convert enum lists to value lists.
-    """
+    """Extract SIPrefix values from StandardPrefixes enums."""
     return [prefix_enum.value for prefix_enum in prefix_enums]
 
 
-# Define which units should get automatic prefixes - using more descriptive type annotation
+# 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
-    
+    "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
+    "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 for optimal performance
+# Initialize lookup caches on module load
 _initialize_lookup_caches()

qnty/units/registry.py

@@ -7,23 +7,24 @@ Unit definitions, constants and registry for the high-performance unit system.
 
 from dataclasses import dataclass
 
-from ..generated.dimensions import DimensionSignature
+from ..dimensions import DimensionSignature
 from .prefixes import SIPrefix, StandardPrefixes
 
 
 @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,43 +33,40 @@ 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."""
-    
-    __slots__ = ('definition', 'name', 'symbol', 'dimension', 'si_factor', '_hash_cache')
-    
+    """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
-        # Cache expensive hash operation
         self._hash_cache = hash(self.name)
-    
-    def __str__(self):
+
+    def __str__(self) -> str:
         return self.symbol
-    
+
     def __eq__(self, other) -> bool:
-        """Ultra-fast equality check for unit constants."""
-        # Fast path: check type first without isinstance() overhead
-        return type(other) is UnitConstant and self.name == other.name
-    
+        """Equality check for unit constants."""
+        return isinstance(other, UnitConstant) and self.name == other.name
+
     def __hash__(self) -> int:
-        """Enable unit constants as dictionary keys with cached hash."""
+        """Enable unit constants as dictionary keys."""
         return self._hash_cache
 
 
 class Registry:
-    """Ultra-fast registry with pre-computed conversion tables."""
-    
-    __slots__ = ('units', 'conversion_table', 'dimensional_groups', '_finalized',
-                 'base_units', 'prefixable_units', '_conversion_cache', '_dimension_cache')
-    
+    """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
@@ -76,48 +74,41 @@ class Registry:
         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
-        # Small cache for frequently used conversions to reduce table lookups
+        # Cache for frequently used conversions
         self._conversion_cache: dict[tuple[str, str], float] = {}
-        # Cache for common dimension mappings (used by variable.py)
+        # 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) -> 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 - optimized to avoid repeated signature access
+
+        # Group by dimension
         dim_sig = unit_def.dimension._signature
-        try:
+        if dim_sig in self.dimensional_groups:
             self.dimensional_groups[dim_sig].append(unit_def)
-        except KeyError:
+        else:
             self.dimensional_groups[dim_sig] = [unit_def]
-    
-    def register_with_prefixes(
-            self,
-            unit_def: UnitDefinition,
-            prefixes: list[StandardPrefixes] | None = None
-        ) -> None:
+
+    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:
@@ -125,7 +116,7 @@ class Registry:
                 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) -> None:
         """Called after all units registered to precompute conversions."""
         if not self._finalized:
@@ -133,58 +124,54 @@ class Registry:
             self._finalized = True
 
     def _precompute_conversions(self) -> None:
-        """Pre-compute all unit conversions for maximum speed with optimized algorithms."""
-        self.conversion_table.clear()  # Clear existing conversions
-        self._conversion_cache.clear()  # Clear cache
-        
+        """Pre-compute all unit conversions for fast lookup."""
+        self.conversion_table.clear()
+        self._conversion_cache.clear()
+
         for group in self.dimensional_groups.values():
-            group_size = len(group)
-            if group_size <= 1:
+            if len(group) <= 1:
                 continue  # Skip groups with single units
-            
-            # Ultra-optimized: pre-compute all factors and names in single pass
-            unit_data = [(unit.name, unit.si_factor) for unit in group]
-            
-            # Vectorized approach: compute all combinations efficiently
-            for i in range(group_size):
-                from_name, from_si = unit_data[i]
-                for j in range(group_size):
-                    if i != j:  # Skip same unit conversion
-                        to_name, to_si = unit_data[j]
-                        # Pre-compute factor - avoid repeated division
-                        factor = from_si / to_si
-                        self.conversion_table[(from_name, to_name)] = factor
-    
+
+            # 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
+                        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 with optimized equality check and caching."""
-        # Ultra-fast path: avoid expensive equality check by comparing names directly
+        """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
-        
-        key = (from_unit.name, to_unit.name)
-        
-        # Check small cache first for frequently used conversions
-        try:
-            return value * self._conversion_cache[key]
-        except KeyError:
-            pass
-        
-        # O(1) lookup for pre-computed conversions
-        try:
-            factor = self.conversion_table[key]
-            # Cache frequently used conversions (keep cache small)
-            if len(self._conversion_cache) < 50:
-                self._conversion_cache[key] = factor
+
+        # 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
-        except KeyError:
-            pass
-        
-        # Fallback (shouldn't happen for registered units)
-        factor = from_unit.si_factor / to_unit.si_factor
-        if len(self._conversion_cache) < 50:
-            self._conversion_cache[key] = 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 high-performance registry
+# 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",
+]