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

qnty/dimensions/signature.py

@@ -0,0 +1,111 @@
+"""
+Dimension Signatures
+====================
+
+Immutable dimension signatures for ultra-fast dimensional analysis using prime number encoding.
+
+This file contains the core DimensionSignature class that provides zero-cost dimensional
+compatibility checking through compile-time type system integration.
+"""
+
+from dataclasses import dataclass
+from typing import ClassVar, final
+
+from .base import BaseDimension
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class DimensionSignature:
+    """Immutable dimension signature for zero-cost dimensional analysis."""
+
+    # Store as bit pattern for ultra-fast comparison
+    _signature: int | float = 1
+
+    # Instance cache for interning common dimensions
+    _INSTANCE_CACHE: ClassVar[dict[int | float, "DimensionSignature"]] = {}
+
+    # Maximum cache size to prevent memory issues
+    _MAX_CACHE_SIZE: ClassVar[int] = 100
+
+    def __new__(cls, signature: int | float = 1):
+        """Optimized constructor with instance interning and validation."""
+        # Input validation
+        if not isinstance(signature, int | float):
+            raise TypeError(f"Signature must be int or float, got {type(signature)}")
+        if signature <= 0:
+            raise ValueError(f"Signature must be positive, got {signature}")
+
+        if signature in cls._INSTANCE_CACHE:
+            return cls._INSTANCE_CACHE[signature]
+
+        instance = object.__new__(cls)
+
+        # Cache common signatures with size limit
+        if len(cls._INSTANCE_CACHE) < cls._MAX_CACHE_SIZE:
+            cls._INSTANCE_CACHE[signature] = instance
+
+        return instance
+
+    @classmethod
+    def create(cls, length: int = 0, mass: int = 0, time: int = 0, current: int = 0, temp: int = 0, amount: int = 0, luminosity: int = 0):
+        """Create dimension from exponents with efficient computation."""
+        # Fast path for dimensionless
+        if not any([length, mass, time, current, temp, amount, luminosity]):
+            return cls(1)
+
+        # Compute signature using tuple of (base, exponent) pairs for efficiency
+        signature = 1.0
+        dimensions = [
+            (BaseDimension.LENGTH, length),
+            (BaseDimension.MASS, mass),
+            (BaseDimension.TIME, time),
+            (BaseDimension.CURRENT, current),
+            (BaseDimension.TEMPERATURE, temp),
+            (BaseDimension.AMOUNT, amount),
+            (BaseDimension.LUMINOSITY, luminosity),
+        ]
+
+        for base, exponent in dimensions:
+            if exponent != 0:
+                signature *= base**exponent
+
+        return cls(signature)
+
+    def __mul__(self, other: "DimensionSignature") -> "DimensionSignature":
+        """Multiply dimensions."""
+        if not isinstance(other, DimensionSignature):
+            raise TypeError(f"Cannot multiply DimensionSignature with {type(other)}")
+        return DimensionSignature(self._signature * other._signature)
+
+    def __truediv__(self, other: "DimensionSignature") -> "DimensionSignature":
+        """Divide dimensions."""
+        if not isinstance(other, DimensionSignature):
+            raise TypeError(f"Cannot divide DimensionSignature by {type(other)}")
+        return DimensionSignature(self._signature / other._signature)
+
+    def __pow__(self, power: int | float) -> "DimensionSignature":
+        """Raise dimension to a power."""
+        if not isinstance(power, int | float):
+            raise TypeError(f"Power must be int or float, got {type(power)}")
+        if power == 1:
+            return self
+        if power == 0:
+            return DimensionSignature(1)
+        return DimensionSignature(self._signature**power)
+
+    def is_compatible(self, other: "DimensionSignature") -> bool:
+        """Check dimensional compatibility."""
+        if not isinstance(other, DimensionSignature):
+            return False
+        return self._signature == other._signature
+
+    def __eq__(self, other: object) -> bool:
+        """Check equality."""
+        if self is other:
+            return True
+        return isinstance(other, DimensionSignature) and self._signature == other._signature
+
+    def __hash__(self) -> int:
+        """Hash based on signature."""
+        return hash(self._signature)

qnty/equations/__init__.py

@@ -0,0 +1,4 @@
+from .equation import Equation
+from .system import EquationSystem
+
+__all__ = ["Equation", "EquationSystem"]

qnty/equations/equation.py

@@ -0,0 +1,220 @@
+"""
+Equation System
+===============
+
+Mathematical equations for qnty variables with solving capabilities.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import cast
+
+from ..constants import SOLVER_DEFAULT_TOLERANCE
+from ..expressions import Expression, VariableReference
+from ..quantities import FieldQnty
+from ..utils.scope_discovery import ScopeDiscoveryService
+
+_logger = logging.getLogger(__name__)
+
+# Global optimization flags
+_SCOPE_DISCOVERY_ENABLED = False  # Disabled by default due to high overhead
+
+
+class Equation:
+    """
+    Represents a mathematical equation with left-hand side equal to right-hand side.
+    Optimized with __slots__ for memory efficiency.
+    """
+
+    __slots__ = ("name", "lhs", "rhs", "_variables")
+
+    def __init__(self, name: str, lhs: FieldQnty | Expression, rhs: Expression):
+        self.name = name
+
+        # Convert Variable to VariableReference if needed - use isinstance for performance
+        if isinstance(lhs, FieldQnty):
+            self.lhs = VariableReference(lhs)
+        else:
+            # It's already an Expression
+            self.lhs = cast(Expression, lhs)
+
+        self.rhs = rhs
+        self._variables: set[str] | None = None  # Lazy initialization for better performance
+
+    def get_all_variables(self) -> set[str]:
+        """Get all variable names used in this equation."""
+        if self._variables is None:
+            # Both lhs and rhs should be Expressions after __init__ conversion
+            lhs_vars = self.lhs.get_variables()
+            rhs_vars = self.rhs.get_variables()
+            self._variables = lhs_vars | rhs_vars
+        return self._variables
+
+    @property
+    def variables(self) -> set[str]:
+        """Get all variable names used in this equation (cached property)."""
+        return self.get_all_variables()
+
+    def get_unknown_variables(self, known_vars: set[str]) -> set[str]:
+        """Get variables that are unknown (not in known_vars set)."""
+        return self.variables - known_vars
+
+    def get_known_variables(self, known_vars: set[str]) -> set[str]:
+        """Get variables that are known (in known_vars set)."""
+        return self.variables & known_vars
+
+    def can_solve_for(self, target_var: str, known_vars: set[str]) -> bool:
+        """Check if this equation can solve for target_var given known_vars."""
+        if target_var not in self.variables:
+            return False
+
+        # Direct assignment case: lhs is the variable
+        if isinstance(self.lhs, VariableReference) and self.lhs.name == target_var:
+            rhs_vars = self.rhs.get_variables()
+            return rhs_vars.issubset(known_vars)
+
+        # General case: can solve if target_var is the only unknown
+        unknown_vars = self.get_unknown_variables(known_vars)
+        return unknown_vars == {target_var}
+
+    def solve_for(self, target_var: str, variable_values: dict[str, FieldQnty]) -> FieldQnty:
+        """
+        Solve the equation for target_var.
+        Returns the target variable with updated quantity.
+        """
+        if target_var not in self.variables:
+            raise ValueError(f"Variable '{target_var}' not found in equation")
+
+        # Only handle direct assignment: target = expression
+        if not (isinstance(self.lhs, VariableReference) and self.lhs.name == target_var):
+            raise NotImplementedError(f"Cannot solve for {target_var} in equation {self}. Only direct assignment equations (var = expression) are supported.")
+
+        # Direct assignment: target_var = rhs
+        result_qty = self.rhs.evaluate(variable_values)
+
+        # Get the variable object to update
+        var_obj = variable_values.get(target_var)
+        if var_obj is None:
+            raise ValueError(f"Variable '{target_var}' not found in variable_values")
+
+        # Convert result to the target variable's original unit if it had one
+        if var_obj.quantity is not None and var_obj.quantity.unit is not None:
+            try:
+                result_qty = result_qty.to(var_obj.quantity.unit)
+            except (ValueError, TypeError, AttributeError) as e:
+                _logger.debug(f"Unit conversion failed for {target_var}: {e}. Using calculated unit.")
+
+        # Update the variable and return it
+        var_obj.quantity = result_qty
+        var_obj.is_known = True
+        return var_obj
+
+    def check_residual(self, variable_values: dict[str, FieldQnty], tolerance: float = SOLVER_DEFAULT_TOLERANCE) -> bool:
+        """
+        Check if equation is satisfied by evaluating residual (LHS - RHS).
+        Returns True if |residual| < tolerance, accounting for units.
+        """
+        try:
+            # Both lhs and rhs should be Expressions after __init__ conversion
+            lhs_value = self.lhs.evaluate(variable_values)
+            rhs_value = self.rhs.evaluate(variable_values)
+
+            # Check dimensional compatibility using public API
+            if not self._are_dimensionally_compatible(lhs_value, rhs_value):
+                return False
+
+            # Convert to same units for comparison
+            rhs_converted = rhs_value.to(lhs_value.unit)
+            residual = abs(lhs_value.value - rhs_converted.value)
+
+            return residual < tolerance
+        except (ValueError, TypeError, AttributeError, KeyError) as e:
+            _logger.debug(f"Expected error in residual check for equation '{self.name}': {e}")
+            return False
+        except Exception as e:
+            error_msg = f"Unexpected error in residual check for equation '{self.name}': {e}"
+            _logger.error(error_msg)
+            raise RuntimeError(error_msg) from e
+
+    def _discover_variables_from_scope(self) -> dict[str, FieldQnty]:
+        """
+        Automatically discover variables from the calling scope using centralized service.
+        """
+        if not _SCOPE_DISCOVERY_ENABLED:
+            return {}
+
+        # Use centralized scope discovery service
+        return ScopeDiscoveryService.discover_variables(self.variables, enable_caching=True)
+
+    def _are_dimensionally_compatible(self, lhs_value, rhs_value) -> bool:
+        """Check if two quantities are dimensionally compatible."""
+        try:
+            # Try to convert - if successful, they're compatible
+            rhs_value.to(lhs_value.unit)
+            return True
+        except (ValueError, TypeError, AttributeError):
+            return False
+
+    def _analyze_variable_states(self, discovered: dict[str, FieldQnty]) -> dict[str, str]:
+        """Analyze which variables are known vs unknown."""
+        states = {}
+        for var_name in self.variables:
+            if var_name not in discovered:
+                states[var_name] = "missing"
+            else:
+                var = discovered[var_name]
+                if hasattr(var, "is_known") and not var.is_known:
+                    states[var_name] = "unknown"
+                elif hasattr(var, "quantity") and var.quantity is not None:
+                    states[var_name] = "known"
+                else:
+                    states[var_name] = "unknown"
+        return states
+
+    def _determine_solvability(self, states: dict[str, str], discovered: dict[str, FieldQnty]) -> tuple[bool, str, dict[str, FieldQnty]]:
+        """Determine if equation can be solved based on variable states."""
+        if "missing" in states.values():
+            return False, "", {}
+
+        unknowns = [name for name, state in states.items() if state == "unknown"]
+
+        # Can only auto-solve if there's exactly one unknown
+        if len(unknowns) == 1:
+            return True, unknowns[0], discovered
+
+        return False, "", {}
+
+    def _can_auto_solve(self) -> tuple[bool, str, dict[str, FieldQnty]]:
+        """Check if equation can be auto-solved from scope using centralized service."""
+        try:
+            discovered = self._discover_variables_from_scope()
+            if not discovered:
+                return False, "", {}
+
+            variable_states = self._analyze_variable_states(discovered)
+            return self._determine_solvability(variable_states, discovered)
+
+        except (AttributeError, KeyError, ValueError, TypeError) as e:
+            _logger.debug(f"Cannot auto-solve equation '{self.name}': {e}")
+            return False, "", {}
+
+    def _try_auto_solve(self) -> bool:
+        """Try to automatically solve the equation if possible."""
+        try:
+            can_solve, target_var, variables = self._can_auto_solve()
+            if can_solve:
+                self.solve_for(target_var, variables)
+                return True
+            return False
+        except (AttributeError, KeyError, ValueError, TypeError) as e:
+            _logger.debug(f"Auto-solve failed for equation '{self.name}': {e}")
+            return False
+
+    def __str__(self) -> str:
+        # Try to auto-solve if possible before displaying
+        self._try_auto_solve()
+        return f"{self.lhs} = {self.rhs}"
+
+    def __repr__(self) -> str:
+        return f"Equation(name='{self.name}', lhs={self.lhs!r}, rhs={self.rhs!r})"

qnty/equations/system.py

@@ -0,0 +1,130 @@
+from ..quantities import FieldQnty
+from .equation import Equation
+
+
+class EquationSystem:
+    """
+    System of equations that can be solved together.
+    Optimized with __slots__ for memory efficiency.
+    """
+
+    __slots__ = ("equations", "variables", "_known_cache", "_unknown_cache")
+
+    def __init__(self, equations: list[Equation] | None = None):
+        self.equations = equations or []
+        self.variables: dict[str, FieldQnty] = {}  # Dict[str, FieldQnty]
+        self._known_cache: set[str] | None = None  # Cache for known variables
+        self._unknown_cache: set[str] | None = None  # Cache for unknown variables
+
+    def add_equation(self, equation: Equation):
+        """Add an equation to the system."""
+        self.equations.append(equation)
+        self._invalidate_caches()
+
+    def add_variable(self, variable: FieldQnty):
+        """Add a variable to the system."""
+        self.variables[variable.name] = variable
+        self._invalidate_caches()
+
+    def _invalidate_caches(self):
+        """Invalidate cached known/unknown variable sets."""
+        self._known_cache = None
+        self._unknown_cache = None
+
+    def _is_variable_known(self, var: FieldQnty) -> bool:
+        """Determine if a variable should be considered known."""
+        return var.is_known and var.quantity is not None
+
+    def get_known_variables(self) -> set[str]:
+        """Get names of all known variables (cached)."""
+        if self._known_cache is None:
+            self._known_cache = {name for name, var in self.variables.items() if self._is_variable_known(var)}
+        return self._known_cache
+
+    def get_unknown_variables(self) -> set[str]:
+        """Get names of all unknown variables (cached)."""
+        if self._unknown_cache is None:
+            self._unknown_cache = {name for name, var in self.variables.items() if not self._is_variable_known(var)}
+        return self._unknown_cache
+
+    def _find_solvable_equation_variable_pair(self, known_vars: set[str], unknown_vars: set[str]) -> tuple[Equation, str] | None:
+        """Find the first equation-variable pair that can be solved."""
+        for equation in self.equations:
+            for unknown_var in unknown_vars:
+                if equation.can_solve_for(unknown_var, known_vars):
+                    return equation, unknown_var
+        return None
+
+    def can_solve_any(self) -> bool:
+        """Check if any equation can be solved with current known variables."""
+        known_vars = self.get_known_variables()
+        unknown_vars = self.get_unknown_variables()
+        return self._find_solvable_equation_variable_pair(known_vars, unknown_vars) is not None
+
+    def solve_step(self) -> bool:
+        """Solve one step - find and solve one equation. Returns True if progress made."""
+        known_vars = self.get_known_variables()
+        unknown_vars = self.get_unknown_variables()
+
+        pair = self._find_solvable_equation_variable_pair(known_vars, unknown_vars)
+        if pair is None:
+            return False
+
+        equation, unknown_var = pair
+        equation.solve_for(unknown_var, self.variables)
+        self._invalidate_caches()
+        return True
+
+    def solve(self, max_iterations: int = 100) -> bool:
+        """Solve the system iteratively. Returns True if fully solved."""
+        if max_iterations <= 0:
+            raise ValueError("max_iterations must be positive")
+
+        for _ in range(max_iterations):
+            if not self.can_solve_any():
+                break
+            if not self.solve_step():
+                break
+
+        # Check if all variables are known
+        unknown_vars = self.get_unknown_variables()
+        return len(unknown_vars) == 0
+
+    def _get_next_solvable_variable(self, simulated_known: set[str]) -> str | None:
+        """Find the next variable that can be solved given current known variables."""
+        unknown_vars = {name for name in self.variables.keys() if name not in simulated_known}
+        if not unknown_vars:
+            return None
+
+        for equation in self.equations:
+            for unknown_var in unknown_vars:
+                if equation.can_solve_for(unknown_var, simulated_known):
+                    return unknown_var
+        return None
+
+    def get_solving_order(self) -> list[str]:
+        """
+        Get the order in which variables can be solved.
+        Optimized to avoid creating full system copies.
+        """
+        order = []
+        simulated_known = self.get_known_variables().copy()
+
+        max_iterations = len(self.variables)  # Prevent infinite loops
+        for _ in range(max_iterations):
+            next_var = self._get_next_solvable_variable(simulated_known)
+            if next_var is None:
+                break
+
+            order.append(next_var)
+            simulated_known.add(next_var)
+
+        return order
+
+    def __str__(self) -> str:
+        known_count = len(self.get_known_variables())
+        total_vars = len(self.variables)
+        return f"EquationSystem({len(self.equations)} equations, {known_count}/{total_vars} variables known)"
+
+    def __repr__(self) -> str:
+        return f"EquationSystem(equations={self.equations!r})"

qnty/expressions/__init__.py

@@ -0,0 +1,40 @@
+"""
+Expression System Package
+=========================
+
+Mathematical expressions for building equation trees with qnty variables.
+"""
+
+# Core AST classes
+# Helper functions
+# Scope discovery service
+from ..utils.scope_discovery import ScopeDiscoveryService
+from .functions import abs_expr, cond_expr, cos, exp, ln, log10, max_expr, min_expr, sin, sqrt, tan
+from .nodes import BinaryOperation, ConditionalExpression, Constant, Expression, UnaryFunction, VariableReference, wrap_operand
+
+# Define public API
+__all__ = [
+    # Core AST classes
+    "Expression",
+    "VariableReference",
+    "Constant",
+    "BinaryOperation",
+    "UnaryFunction",
+    "ConditionalExpression",
+    # Helper functions
+    "sin",
+    "cos",
+    "tan",
+    "sqrt",
+    "abs_expr",
+    "ln",
+    "log10",
+    "exp",
+    "cond_expr",
+    "min_expr",
+    "max_expr",
+    # Utilities
+    "wrap_operand",
+    # Scope discovery
+    "ScopeDiscoveryService",
+]