qnty 0.0.1__py3-none-any.whl → 0.0.2__py3-none-any.whl

qnty/variable.py

@@ -2,21 +2,36 @@
 High-Performance Quantity and Variables
 ========================================
 
-FastQuantity class and type-safe variables optimized for engineering calculations 
+FastQuantity class and type-safe variables optimized for engineering calculations
 with dimensional safety.
 """
 
-from typing import Union, Optional, TypeVar, Generic, TYPE_CHECKING
-from .dimension import DimensionSignature, DIMENSIONLESS, LENGTH, PRESSURE, AREA, VOLUME, FORCE, ENERGY
+from __future__ import annotations
+
+from typing import Generic, Self, TypeVar
+
+from .dimension import AREA, DIMENSIONLESS, ENERGY, FORCE, LENGTH, PRESSURE, VOLUME, DimensionSignature
 from .unit import UnitConstant, UnitDefinition, registry
 from .units import DimensionlessUnits, LengthUnits, PressureUnits
 
-if TYPE_CHECKING:
-    from .setters import TypeSafeSetter, LengthSetter, PressureSetter
+# TypeVar for generic dimensional types
+DimensionType = TypeVar('DimensionType', bound='FastQuantity')
 
 
-DimensionType = TypeVar('DimensionType', bound='FastQuantity')
-SetterType = TypeVar('SetterType')
+class TypeSafeSetter:
+    """Basic type-safe setter that accepts compatible units."""
+    
+    def __init__(self, variable: TypeSafeVariable, value: float):
+        self.variable = variable
+        self.value = value
+    
+    def with_unit(self, unit: UnitConstant) -> TypeSafeVariable:
+        """Set with type-safe unit constant."""
+        if not self.variable.expected_dimension.is_compatible(unit.dimension):
+            raise TypeError(f"Unit {unit.name} incompatible with expected dimension")
+        
+        self.variable.quantity = FastQuantity(self.value, unit)
+        return self.variable
 
 
 class FastQuantity:
@@ -39,7 +54,7 @@ class FastQuantity:
         return f"FastQuantity({self.value}, {self.unit.name})"
     
     # Ultra-fast arithmetic with dimensional checking
-    def __add__(self, other: 'FastQuantity') -> 'FastQuantity':
+    def __add__(self, other: FastQuantity) -> FastQuantity:
         # Fast dimension compatibility check using cached signatures
         if self._dimension_sig != other._dimension_sig:
             raise ValueError(f"Cannot add {self.unit.name} and {other.unit.name}")
@@ -52,7 +67,7 @@ class FastQuantity:
         other_value = other.value * other._si_factor / self._si_factor
         return FastQuantity(self.value + other_value, self.unit)
     
-    def __sub__(self, other: 'FastQuantity') -> 'FastQuantity':
+    def __sub__(self, other: FastQuantity) -> FastQuantity:
         # Fast dimension compatibility check using cached signatures
         if self._dimension_sig != other._dimension_sig:
             raise ValueError(f"Cannot subtract {other.unit.name} from {self.unit.name}")
@@ -65,8 +80,8 @@ class FastQuantity:
         other_value = other.value * other._si_factor / self._si_factor
         return FastQuantity(self.value - other_value, self.unit)
     
-    def __mul__(self, other: Union['FastQuantity', float, int]) -> 'FastQuantity':
-        if isinstance(other, (int, float)):
+    def __mul__(self, other: FastQuantity | float | int) -> FastQuantity:
+        if isinstance(other, int | float):
             return FastQuantity(self.value * other, self.unit)
         
         # Fast dimensional analysis using cached signatures
@@ -83,14 +98,14 @@ class FastQuantity:
         
         return FastQuantity(result_value, result_unit)
     
-    def __rmul__(self, other: Union[float, int]) -> 'FastQuantity':
+    def __rmul__(self, other: float | int) -> FastQuantity:
         """Reverse multiplication for cases like 2 * quantity."""
-        if isinstance(other, (int, float)):
+        if isinstance(other, int | float):
             return FastQuantity(other * self.value, self.unit)
         return NotImplemented
     
-    def __truediv__(self, other: Union['FastQuantity', float, int]) -> 'FastQuantity':
-        if isinstance(other, (int, float)):
+    def __truediv__(self, other: FastQuantity | float | int) -> FastQuantity:
+        if isinstance(other, int | float):
             return FastQuantity(self.value / other, self.unit)
         
         # Fast dimensional analysis using cached signatures
@@ -107,8 +122,8 @@ class FastQuantity:
         
         return FastQuantity(result_value, result_unit)
     
-    def _find_result_unit_fast(self, result_dimension_sig: int, 
-                              left_qty: 'FastQuantity', right_qty: 'FastQuantity') -> UnitConstant:
+    def _find_result_unit_fast(self, result_dimension_sig: int,
+                              left_qty: FastQuantity, right_qty: FastQuantity) -> UnitConstant:
         """Ultra-fast unit finding using cached dimension signatures."""
         
         # Initialize dimension cache if empty
@@ -130,7 +145,7 @@ class FastQuantity:
         # For rare combined dimensions, create temporary unit
         temp_unit = UnitDefinition(
             name=f"combined_{result_dimension_sig}",
-            symbol="combined", 
+            symbol="combined",
             dimension=DimensionSignature(result_dimension_sig),
             si_factor=1.0
         )
@@ -140,13 +155,13 @@ class FastQuantity:
         registry._dimension_cache[result_dimension_sig] = result_unit
         return result_unit
     
-    def _find_result_unit(self, result_dimension: DimensionSignature, 
-                         left_qty: 'FastQuantity', right_qty: 'FastQuantity') -> UnitConstant:
+    def _find_result_unit(self, result_dimension: DimensionSignature,
+                         left_qty: FastQuantity, right_qty: FastQuantity) -> UnitConstant:
         """Legacy method - kept for compatibility."""
         return self._find_result_unit_fast(result_dimension._signature, left_qty, right_qty)
     
     # Ultra-fast comparisons
-    def __lt__(self, other: 'FastQuantity') -> bool:
+    def __lt__(self, other: FastQuantity) -> bool:
         if self._dimension_sig != other._dimension_sig:
             raise ValueError("Cannot compare incompatible dimensions")
         
@@ -172,7 +187,7 @@ class FastQuantity:
         other_value = other.value * other._si_factor / self._si_factor
         return abs(self.value - other_value) < 1e-10
     
-    def to(self, target_unit: UnitConstant) -> 'FastQuantity':
+    def to(self, target_unit: UnitConstant) -> FastQuantity:
         """Ultra-fast unit conversion."""
         if self.unit == target_unit:
             return FastQuantity(self.value, target_unit)
@@ -183,16 +198,40 @@ class FastQuantity:
 
 
 class TypeSafeVariable(Generic[DimensionType]):
-    """Type-safe variable with compile-time dimensional checking."""
+    """
+    Base class for type-safe variables with dimensional checking.
     
-    def __init__(self, name: str, expected_dimension: DimensionSignature):
+    This is a simple data container without dependencies on expressions or equations.
+    Mathematical operations are added by subclasses or mixins.
+    """
+    
+    # Class attribute defining which setter to use - subclasses can override
+    _setter_class = TypeSafeSetter
+    
+    def __init__(self, name: str, expected_dimension, is_known: bool = True):
         self.name = name
+        self.symbol: str | None = None  # Will be set by EngineeringProblem to attribute name
         self.expected_dimension = expected_dimension
-        self.quantity: Optional[FastQuantity] = None
+        self.quantity: FastQuantity | None = None
+        self.is_known = is_known
+    
+    def set(self, value: float):
+        """Create a setter for this variable using the class-specific setter type."""
+        return self._setter_class(self, value)
     
-    def set(self, value: float) -> Union['TypeSafeSetter', 'LengthSetter', 'PressureSetter']:
-        from .setters import TypeSafeSetter
-        return TypeSafeSetter(self, value)
+    @property
+    def unknown(self) -> Self:
+        """Mark this variable as unknown using fluent API."""
+        self.is_known = False
+        return self
+    
+    @property
+    def known(self) -> Self:
+        """Mark this variable as known using fluent API."""
+        self.is_known = True
+        return self
     
     def __str__(self):
-        return f"{self.name}: {self.quantity}" if self.quantity else f"{self.name}: unset"
+        return f"{self.name}: {self.quantity}" if self.quantity else f"{self.name}: unset"
+
+

qnty/variables.py

@@ -1,31 +1,229 @@
 """
-Specialized Variables
-=====================
+Specialized Variables and Setters
+==================================
 
-Dimension-specific variable classes with type safety.
+Dimension-specific variable classes with type safety, fluent API setters,
+and mathematical operations for expressions and equations.
 """
 
-from .dimension import LENGTH, PRESSURE
-from .variable import TypeSafeVariable
-from .setters import LengthSetter, PressureSetter
+from __future__ import annotations
 
+from typing import cast
 
-# Specialized variable types  
-class Length(TypeSafeVariable):
-    """Type-safe length variable."""
+from .dimension import DIMENSIONLESS, LENGTH, PRESSURE
+from .equation import Equation
+from .expression import Expression, wrap_operand
+from .units import DimensionlessUnits, LengthUnits, PressureUnits
+from .variable import FastQuantity, TypeSafeSetter, TypeSafeVariable
+
+
+class ExpressionVariable(TypeSafeVariable):
+    """
+    TypeSafeVariable extended with expression and equation capabilities.
+    
+    This adds mathematical operations that create expressions and equations,
+    keeping the base TypeSafeVariable free of these dependencies.
+    """
+    
+    def equals(self, expression: Expression | TypeSafeVariable | FastQuantity | int | float):
+        """Create an equation: self = expression."""
+        # Wrap the expression in proper Expression type
+        rhs_expr = wrap_operand(expression)
+        return Equation(f"{self.name}_eq", self, rhs_expr)
+    
+    def __add__(self, other: TypeSafeVariable | FastQuantity | int | float) -> Expression:
+        """Add this variable to another operand, returning an Expression."""
+        return wrap_operand(self) + wrap_operand(other)
+
+    def __radd__(self, other: FastQuantity | int | float) -> Expression:
+        """Reverse add for this variable."""
+        return wrap_operand(other) + wrap_operand(self)
+    
+    def __sub__(self, other: TypeSafeVariable | FastQuantity | int | float) -> Expression:
+        """Subtract another operand from this variable, returning an Expression."""
+        return wrap_operand(self) - wrap_operand(other)
+    
+    def __rsub__(self, other: FastQuantity | int | float) -> Expression:
+        """Reverse subtract for this variable."""
+        return wrap_operand(other) - wrap_operand(self)
+    
+    def __mul__(self, other: TypeSafeVariable | FastQuantity | int | float) -> Expression:
+        """Multiply this variable by another operand, returning an Expression."""
+        return wrap_operand(self) * wrap_operand(other)
+    
+    def __rmul__(self, other: FastQuantity | int | float) -> Expression:
+        """Reverse multiply for this variable."""
+        return wrap_operand(other) * wrap_operand(self)
     
-    def __init__(self, name: str):
-        super().__init__(name, LENGTH)
+    def __truediv__(self, other: TypeSafeVariable | FastQuantity | int | float) -> Expression:
+        """Divide this variable by another operand, returning an Expression."""
+        return wrap_operand(self) / wrap_operand(other)
+
+    def __rtruediv__(self, other: FastQuantity | int | float) -> Expression:
+        """Reverse divide for this variable."""
+        return wrap_operand(other) / wrap_operand(self)
+    
+    def __pow__(self, other: TypeSafeVariable | FastQuantity | int | float) -> Expression:
+        """Raise this variable to a power, returning an Expression."""
+        return wrap_operand(self) ** wrap_operand(other)
+
+    def __rpow__(self, other: FastQuantity | int | float) -> Expression:
+        """Reverse power for this variable."""
+        return wrap_operand(other) ** wrap_operand(self)
+
+
+# Specialized setter classes
+class LengthSetter(TypeSafeSetter):
+    """Length-specific setter with only length units."""
     
-    def set(self, value: float) -> 'LengthSetter':
-        return LengthSetter(self, value)
+    def __init__(self, variable: Length, value: float):
+        super().__init__(variable, value)
+    
+    # Only length units available - compile-time safe!
+    @property
+    def meters(self) -> Length:
+        self.variable.quantity = FastQuantity(self.value, LengthUnits.meter)
+        return cast(Length, self.variable)
+    
+    @property
+    def millimeters(self) -> Length:
+        self.variable.quantity = FastQuantity(self.value, LengthUnits.millimeter)
+        return cast(Length, self.variable)
+    
+    @property
+    def inches(self) -> Length:
+        self.variable.quantity = FastQuantity(self.value, LengthUnits.inch)
+        return cast(Length, self.variable)
+    
+    @property
+    def feet(self) -> Length:
+        self.variable.quantity = FastQuantity(self.value, LengthUnits.foot)
+        return cast(Length, self.variable)
 
 
-class Pressure(TypeSafeVariable):
-    """Type-safe pressure variable."""
+class PressureSetter(TypeSafeSetter):
+    """Pressure-specific setter with only pressure units."""
+    
+    def __init__(self, variable: Pressure, value: float):
+        super().__init__(variable, value)
     
-    def __init__(self, name: str):
-        super().__init__(name, PRESSURE)
+    # Only pressure units available - compile-time safe!
+    @property
+    def psi(self) -> Pressure:
+        self.variable.quantity = FastQuantity(self.value, PressureUnits.psi)
+        return cast(Pressure, self.variable)
     
-    def set(self, value: float) -> 'PressureSetter':
-        return PressureSetter(self, value)
+    @property
+    def kPa(self) -> Pressure:
+        self.variable.quantity = FastQuantity(self.value, PressureUnits.kilopascal)
+        return cast(Pressure, self.variable)
+    
+    @property
+    def MPa(self) -> Pressure:
+        self.variable.quantity = FastQuantity(self.value, PressureUnits.megapascal)
+        return cast(Pressure, self.variable)
+    
+    @property
+    def bar(self) -> Pressure:
+        self.variable.quantity = FastQuantity(self.value, PressureUnits.bar)
+        return cast(Pressure, self.variable)
+
+
+class DimensionlessSetter(TypeSafeSetter):
+    """Dimensionless-specific setter with only dimensionless units."""
+    
+    def __init__(self, variable: Dimensionless, value: float):
+        super().__init__(variable, value)
+    
+    # Dimensionless units
+    @property
+    def dimensionless(self) -> Dimensionless:
+        self.variable.quantity = FastQuantity(self.value, DimensionlessUnits.dimensionless)
+        return cast(Dimensionless, self.variable)
+    
+    # Common alias for no units
+    @property
+    def unitless(self) -> Dimensionless:
+        self.variable.quantity = FastQuantity(self.value, DimensionlessUnits.dimensionless)
+        return cast(Dimensionless, self.variable)
+
+
+# Specialized variable types that users interact with
+class Length(ExpressionVariable):
+    """Type-safe length variable with expression capabilities."""
+    
+    _setter_class = LengthSetter
+    
+    def __init__(self, *args, is_known: bool = True):
+        if len(args) == 1:
+            # Length("name") - original syntax
+            super().__init__(args[0], LENGTH, is_known=is_known)
+        elif len(args) == 3:
+            # Length(value, "unit", "name") - new syntax
+            value, unit, name = args
+            super().__init__(name, LENGTH, is_known=is_known)
+            # Auto-set the value with the specified unit
+            setter = LengthSetter(self, value)
+            # Get the unit setter method dynamically
+            if unit == "in":  # Handle "in" alias for inches
+                setter.inches
+            elif hasattr(setter, unit):
+                getattr(setter, unit)
+            elif hasattr(setter, unit + 's'):  # Handle singular/plural
+                getattr(setter, unit + 's')
+            else:
+                # Default to meters if unit not recognized
+                setter.meters
+        else:
+            raise ValueError("Length expects either 1 argument (name) or 3 arguments (value, unit, name)")
+
+
+class Pressure(ExpressionVariable):
+    """Type-safe pressure variable with expression capabilities."""
+    
+    _setter_class = PressureSetter
+    
+    def __init__(self, *args, is_known: bool = True):
+        if len(args) == 1:
+            # Pressure("name") - original syntax
+            super().__init__(args[0], PRESSURE, is_known=is_known)
+        elif len(args) == 3:
+            # Pressure(value, "unit", "name") - new syntax
+            value, unit, name = args
+            super().__init__(name, PRESSURE, is_known=is_known)
+            # Auto-set the value with the specified unit
+            setter = PressureSetter(self, value)
+            # Get the unit setter method dynamically
+            if unit == "psi":
+                setter.psi
+            elif unit == "kPa":
+                setter.kPa
+            elif unit == "MPa":
+                setter.MPa
+            elif unit == "bar":
+                setter.bar
+            else:
+                # Default to psi if unit not recognized
+                setter.psi
+        else:
+            raise ValueError("Pressure expects either 1 argument (name) or 3 arguments (value, unit, name)")
+
+
+class Dimensionless(ExpressionVariable):
+    """Type-safe dimensionless variable with expression capabilities."""
+
+    _setter_class = DimensionlessSetter
+
+    def __init__(self, *args, is_known: bool = True):
+        if len(args) == 1:
+            # Dimensionless("name") - original syntax
+            super().__init__(args[0], DIMENSIONLESS, is_known=is_known)
+        elif len(args) == 2:
+            # Dimensionless(value, "name") - new syntax
+            value, name = args
+            super().__init__(name, DIMENSIONLESS, is_known=is_known)
+            # Auto-set the value as dimensionless
+            setter = DimensionlessSetter(self, value)
+            setter.dimensionless
+        else:
+            raise ValueError("Dimensionless expects either 1 argument (name) or 2 arguments (value, name)")

{qnty-0.0.1.dist-info → qnty-0.0.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: qnty
-Version: 0.0.1
+Version: 0.0.2
 Summary: High-performance unit system library for Python with dimensional safety and fast unit conversions
 License: Apache-2.0
 Keywords: units,dimensional analysis,engineering,physics,quantities,measurements
@@ -33,7 +33,7 @@ Description-Content-Type: text/markdown
 
 **High-performance unit system library for Python with dimensional safety and fast unit conversions for engineering calculations.**
 
-[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Development Status](https://img.shields.io/badge/status-beta-orange.svg)](https://pypi.org/project/qnty/)
 
@@ -43,7 +43,7 @@ Description-Content-Type: text/markdown
 
 **📐 Accuracy Notice**: The authors are not responsible or liable for incorrect results, calculation errors, or any consequences arising from the use of this library. Always validate calculations independently using established engineering tools and practices.
 
-**🚀 Learn from History**: Remember, even NASA's Mars Climate Orbiter had a $327 million oops moment due to unit conversion errors between metric and imperial systems. Don't let your project become the next cautionary tale - double-check everything! 
+**🚀 Learn from History**: Remember, even NASA's Mars Climate Orbiter had a $327 million oops moment due to unit conversion errors between metric and imperial systems. Don't let your project become the next cautionary tale - double-check everything!
 
 *Use Qnty to help prevent unit errors, but always verify critical calculations through multiple methods.*
 
@@ -58,7 +58,9 @@ Qnty is designed around **type safety** and **performance optimization** using c
 - **⚡ Zero-Cost Abstractions**: Optimized operations with `__slots__` and caching
 - **🔗 Fluent API**: Intuitive method chaining for readable code
 - **🧮 Engineering-Focused**: Built for real-world engineering calculations
-- **📊 Comprehensive Testing**: 400+ tests with performance benchmarks
+- **🧬 Mathematical System**: Built-in equation solving and expression trees
+- **📊 Comprehensive Testing**: 457 tests with performance benchmarks
+- **🏗️ Clean Architecture**: Circular import-free design with strict dependency hierarchy
 
 ## 🚀 Quick Start
 
@@ -73,7 +75,7 @@ poetry add qnty
 ### Basic Usage
 
 ```python
-from qnty.variables import Length, Pressure
+from qnty import Length, Pressure, Dimensionless
 from qnty.variable import FastQuantity
 from qnty.units import LengthUnits, PressureUnits
 
@@ -95,7 +97,7 @@ force = pressure * area  # Automatic dimensional analysis
 ### Engineering Example
 
 ```python
-from qnty.variables import Length, Pressure
+from qnty import Length, Pressure
 
 # ASME pressure vessel calculation with mixed units
 pressure = Pressure("internal_pressure")
@@ -112,47 +114,90 @@ thickness = (pressure.quantity * diameter.quantity) / (2 * stress.quantity)
 print(f"Required thickness: {thickness}")  # Automatically in correct units
 ```
 
+### Mathematical Equations & Solving
+
+```python
+from qnty import Length, Pressure, Dimensionless
+
+# Define engineering variables
+T = Length("Wall Thickness", is_known=False)  # Unknown to solve for
+T_bar = Length(0.147, "inches", "Nominal Wall Thickness")
+U_m = Dimensionless(0.125, "Mill Undertolerance")
+
+# Create equation using fluent API: T = T_bar * (1 - U_m)
+equation = T.equals(T_bar * (1 - U_m))
+
+# Solve automatically
+known_vars = {"T_bar": T_bar, "U_m": U_m}
+result = equation.solve_for("T", known_vars)
+print(f"Solved thickness: {result.quantity}")  # 0.128625 inches
+
+# Verify equation is satisfied
+assert equation.check_residual(known_vars) is True
+```
+
 ## 🏗️ Architecture
 
+### Clean Dependency Design
+
+Qnty features a carefully designed architecture that eliminates circular imports through a strict dependency hierarchy:
+
+```python
+variable → variables → expression → equation
+```
+
+This ensures clean type checking, maintainable code, and optimal performance throughout the system.
+
 ### Core Components
 
-**🔢 Dimensional System**
+### 🔢 Dimensional System
+
 - Prime number encoding for ultra-fast dimensional compatibility checks
 - Zero-cost dimensional analysis at compile time
 - Immutable dimension signatures for thread safety
 
-**⚙️ High-Performance Quantities**
+### ⚙️ High-Performance Quantities
+
 - `FastQuantity`: Optimized for engineering calculations with `__slots__`
 - Cached SI factors and dimension signatures
 - Fast-path optimizations for same-unit operations
 
-**🎯 Type-Safe Variables**
-- `Length`, `Pressure`: Domain-specific variables with compile-time safety
+### 🎯 Type-Safe Variables
+
+- `Length`, `Pressure`, `Dimensionless`: Domain-specific variables with compile-time safety
 - Fluent API with specialized setters
 - Prevents dimensional errors at the type level
 
-**🔄 Smart Unit System**
+### 🔄 Smart Unit System
+
 - Pre-computed conversion tables
 - Automatic unit resolution for calculations
 - Support for mixed-unit operations
 
+### 🧬 Mathematical System
+
+- Built-in equation solving with symbolic manipulation
+- Expression trees for complex mathematical operations
+- Automatic residual checking and validation
+- Engineering equation support (ASME, pressure vessels, etc.)
+
 ## 📊 Performance
 
-Qnty significantly outperforms other unit libraries with **23.7x average speedup** over Pint:
+Qnty significantly outperforms other unit libraries with **18.9x average speedup** over Pint:
 
 ### Real Benchmark Results (μs per operation)
 
 | Operation | Qnty | Pint | **Speedup** |
 |-----------|------|------|-------------|
-| Unit Conversion (m → mm) | 0.60 | 14.03 | **23.5x** |
-| Mixed Unit Addition (mm + in) | 1.14 | 31.80 | **28.0x** |
-| Multiplication (m × m) | 0.91 | 14.13 | **15.5x** |
-| Division (psi ÷ mm) | 1.01 | 16.29 | **16.1x** |
-| Complex ASME Equation | 5.46 | 180.95 | **33.1x** 🚀 |
-| Type-Safe Variables | 1.08 | 24.80 | **23.0x** |
-| Chained Operations | 3.93 | 88.94 | **22.6x** |
-| Loop (10 additions) | 6.49 | 118.21 | **18.2x** |
-| **AVERAGE** | **2.58** | **61.14** | **23.7x** 🏆 |
+| Unit Conversion (m → mm) | 0.50 | 9.72 | **19.5x** |
+| Mixed Unit Addition (mm + in) | 0.76 | 17.52 | **23.1x** |
+| Multiplication (m × m) | 0.82 | 10.64 | **12.9x** |
+| Division (psi ÷ mm) | 0.87 | 11.23 | **12.9x** |
+| Complex ASME Equation | 4.07 | 106.17 | **26.1x** 🚀 |
+| Type-Safe Variables | 0.98 | 9.65 | **9.8x** |
+| Chained Operations | 1.83 | 42.22 | **23.1x** |
+| Loop (10 additions) | 5.32 | 79.48 | **14.9x** |
+| **AVERAGE** | **1.89** | **35.83** | **18.9x** 🏆 |
 
 *Benchmarks performed on typical engineering calculations. Run `pytest tests/test_benchmark.py -v -s` to verify on your system.*
 
@@ -197,6 +242,44 @@ area = width.quantity * height.quantity
 perimeter = 2 * (width.quantity + height.quantity)
 ```
 
+### Equation Solving System
+
+```python
+from qnty import Length, Pressure, Dimensionless
+
+# Multi-variable engineering equations
+P = Pressure(90, "psi", "P")  # Known
+D = Length(0.84, "inches", "D")  # Known
+t = Length("t", is_known=False)  # Unknown - solve for this
+S = Pressure(20000, "psi", "S")  # Known
+
+# ASME pressure vessel equation: P = (S * t) / ((D/2) + 0.6*t)
+# Rearranged to solve for t
+equation = t.equals((P * D) / (2 * S - 1.2 * P))
+
+# Solve automatically
+known_variables = {"P": P, "D": D, "S": S}
+thickness_result = equation.solve_for("t", known_variables)
+print(f"Required thickness: {thickness_result.quantity}")
+
+# Verify solution
+assert equation.check_residual(known_variables) is True
+```
+
+### Import Strategy
+
+Qnty provides a clean, minimal public API:
+
+```python
+# Preferred import style - clean public API
+from qnty import Length, Pressure, Dimensionless
+
+# Internal imports when needed for advanced usage
+from qnty.variable import FastQuantity, TypeSafeVariable
+from qnty.expression import Expression
+from qnty.equation import Equation, EquationSystem
+```
+
 ## 🔧 Development
 
 ### Setup Development Environment
@@ -221,6 +304,7 @@ python tests/test_benchmark.py
 ```bash
 # Linting with ruff (200 character line length)
 ruff check src/ tests/
+ruff format src/ tests/
 
 # Type checking
 mypy src/qnty/
@@ -232,7 +316,9 @@ mypy src/qnty/
 
 - **`FastQuantity`**: High-performance quantity with value and unit
 - **`TypeSafeVariable`**: Base class for dimension-specific variables
-- **`Length`**, **`Pressure`**: Specialized variables with fluent setters
+- **`Length`**, **`Pressure`**, **`Dimensionless`**: Specialized variables with fluent setters
+- **`Equation`**: Mathematical equations with solving capabilities
+- **`Expression`**: Abstract base for mathematical expression trees
 - **`DimensionSignature`**: Immutable dimension encoding system
 - **`UnitConstant`**: Type-safe unit definitions
 
@@ -266,3 +352,4 @@ This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENS
 ---
 
 **Ready to supercharge your engineering calculations?** Install Qnty today and experience the power of type-safe, high-performance unit handling! 🚀
+

qnty-0.0.2.dist-info/RECORD

@@ -0,0 +1,11 @@
+qnty/__init__.py,sha256=wzFXh3bgSbjHzg1tHYRwEcEO25mijhsdohHUQDibVu4,106
+qnty/dimension.py,sha256=X9v4_-8IhLcUsXzYgC6rXaGZ-Y6tqB8MPZgN9re_lx8,2781
+qnty/equation.py,sha256=XgzM91jn__GomKbgslncoFJWPDJiMb4_VKD-8sdcFXc,9096
+qnty/expression.py,sha256=UM0hCqOVD1gK_O5-Rsq7BWIPDTEL_kFORprV6LIqGcU,20890
+qnty/unit.py,sha256=dgJX6rcbeAv6NFyQtrT-Zp7m93X39GlU9jkcRYBKic4,4187
+qnty/units.py,sha256=uazbYoC3sFE6MKd46f2BrysmgJ-r0v7BvKGsvw8a2W0,1367
+qnty/variable.py,sha256=6Z-QmLE3ke2fdw-d6hNR7OSC7aAhE02htHY5XTN7zgI,9808
+qnty/variables.py,sha256=_dchFWFOedWkGDMC4AhZ_kHEM6VVH7iqANksVyfHoLc,9039
+qnty-0.0.2.dist-info/METADATA,sha256=90UoHneLF5m66UFkdjV84C5KohJVBxMy0wzx1LN8rD0,12113
+qnty-0.0.2.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+qnty-0.0.2.dist-info/RECORD,,