Metadata-Version: 2.4
Name: unit-aware-arithmetic
Version: 1.0.0
Summary: Type-safe dimensional arithmetic library with unit tracking
Home-page: https://github.com/parthivrawat/unit-aware-arithmetic
Author: Parthiv Rawat
Author-email: Parthiv Rawat <parthiv05022000@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Parthiv Rawat
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/parthivrawat/unit-aware-arithmetic
Project-URL: Repository, https://github.com/parthivrawat/unit-aware-arithmetic.git
Project-URL: Issues, https://github.com/parthivrawat/unit-aware-arithmetic/issues
Keywords: units,dimensions,physics,measurement,type-safe,dimensional-analysis
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# Unit-Aware Arithmetic (Python)

A type-safe dimensional arithmetic library that tracks units at runtime and prevents invalid operations.

## Features

- ✅ **Type-safe dimensional analysis**: Prevents incompatible unit operations
- ✅ **Zero dependencies**: Core functionality has no external dependencies
- ✅ **Comprehensive unit coverage**: SI, imperial, and derived units
- ✅ **Arithmetic operations**: Add, subtract, multiply, divide with unit tracking
- ✅ **Unit conversion**: Automatic and explicit conversion between compatible units
- ✅ **Clear error messages**: Helpful errors for incompatible operations
- ✅ **Production-ready**: Comprehensive test coverage (>95%)

## Installation

```bash
pip install -e .
```

## Quick Start

```python
from dimensional import Quantity, units

# Create quantities with units
distance = Quantity(100, units.meter)
time = Quantity(9.58, units.second)

# Arithmetic operations with automatic unit tracking
speed = distance / time
print(speed)  # 10.438413361169102 m/s

# Unit conversion
distance_km = distance.to(units.kilometer)
print(distance_km)  # 0.1 km

# Type-safe operations - this will raise an error!
try:
    distance + time  # IncompatibleUnitsError
except Exception as e:
    print(f"Error: {e}")
```

## Usage Examples

### Basic Arithmetic

```python
from dimensional import Quantity, units

# Addition (same dimension required)
d1 = Quantity(5, units.meter)
d2 = Quantity(3, units.meter)
total = d1 + d2  # 8.0 m

# Multiplication creates derived units
area = Quantity(5, units.meter) * Quantity(3, units.meter)
print(area)  # 15.0 m·m

# Division creates derived units
velocity = Quantity(100, units.meter) / Quantity(10, units.second)
print(velocity)  # 10.0 m/s
```

### Unit Conversion

```python
from dimensional import Quantity, units

# Length conversion
distance = Quantity(1, units.mile)
distance_km = distance.to(units.kilometer)
print(distance_km)  # 1.60934 km

# Temperature conversion
temp_c = Quantity(0, units.celsius)
temp_k = temp_c.to(units.kelvin)
print(temp_k)  # 273.15 K

# Mass conversion
mass_lb = Quantity(10, units.pound)
mass_kg = mass_lb.to(units.kilogram)
print(mass_kg)  # 4.53592 kg
```

### Physics Calculations

```python
from dimensional import Quantity, units

# Calculate velocity
distance = Quantity(100, units.meter)
time = Quantity(9.58, units.second)
velocity = distance / time
print(f"Velocity: {velocity}")

# Calculate force (F = ma)
mass = Quantity(10, units.kilogram)
acceleration = Quantity(9.8, units.meter_per_second_squared)
force = mass * acceleration
print(f"Force: {force}")

# Calculate kinetic energy (KE = 1/2 * m * v²)
mass = Quantity(2, units.kilogram)
velocity = Quantity(10, units.meter_per_second)
ke = 0.5 * mass * (velocity ** 2)
print(f"Kinetic Energy: {ke}")
```

### Comparison Operations

```python
from dimensional import Quantity, units

d1 = Quantity(100, units.centimeter)
d2 = Quantity(1, units.meter)

# Automatic conversion for comparison
print(d1 == d2)  # True
print(d1 < Quantity(2, units.meter))  # True
```

## Available Units

### Length
- `meter`, `kilometer`, `centimeter`, `millimeter`
- `inch`, `foot`, `yard`, `mile`

### Mass
- `kilogram`, `gram`, `milligram`, `tonne`
- `pound`, `ounce`

### Time
- `second`, `minute`, `hour`, `day`

### Temperature
- `kelvin`, `celsius`, `fahrenheit`

### Current
- `ampere`, `milliampere`

### Derived Units
- `newton` (force)
- `joule`, `kilojoule` (energy)
- `watt`, `kilowatt` (power)
- `pascal`, `kilopascal` (pressure)
- `meter_per_second`, `kilometer_per_hour` (velocity)
- `meter_per_second_squared` (acceleration)

## Error Handling

The library provides clear error messages for invalid operations:

```python
from dimensional import Quantity, units, IncompatibleUnitsError

distance = Quantity(100, units.meter)
time = Quantity(10, units.second)

try:
    # This will raise IncompatibleUnitsError
    result = distance + time
except IncompatibleUnitsError as e:
    print(e)  # "Cannot add m and s: incompatible dimensions"
```

## Testing

Run the test suite:

```bash
pytest test_dimensional.py -v
```

Run with coverage:

```bash
pytest test_dimensional.py --cov=dimensional --cov-report=html
```

## Type Checking

This library includes type hints. Run type checking with:

```bash
mypy dimensional.py
```

## Design Principles

1. **Zero Dependencies**: Core functionality has no external dependencies
2. **Type Safety**: Prevents invalid operations at runtime
3. **Clear Errors**: Actionable error messages
4. **Production Ready**: Comprehensive test coverage
5. **Performance**: Efficient implementation with minimal overhead

## API Reference

### `Dimension`

Represents the dimensional formula of a unit (e.g., L^1 T^-2 for acceleration).

### `Unit`

Represents a unit of measurement with its dimension and conversion factor.

### `Quantity`

A numeric value with an associated unit. Supports:
- Arithmetic: `+`, `-`, `*`, `/`, `**`, `-` (negation), `abs()`
- Comparison: `==`, `!=`, `<`, `<=`, `>`, `>=`
- Conversion: `.to(target_unit)`

### `units`

Namespace containing all predefined units.

## License

MIT License

## Contributing

Contributions are welcome! Please ensure:
- All tests pass
- Code coverage remains >90%
- Type hints are included
- Documentation is updated

## Changelog

### 1.0.0 (2026-08-28)
- Initial release
- Support for SI and imperial units
- Comprehensive dimensional analysis
- Temperature conversion with offset handling
- Full test coverage
