Metadata-Version: 2.4
Name: unitforge
Version: 0.6.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Rust
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Dist: numpy>=2.2.0
Requires-Dist: typing-extensions>=4.0
Summary: A library for unit and quantity consistent computations in Rust
Keywords: units,quantities,simulation,physics
Author: Dr.Q team <info@askdrq.com>, Henrik Stromberg <henrik@askdrq.com>
Author-email: "Dr.Q team" <info@askdrq.com>, Henrik Stromberg <henrik@askdrq.com>
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Repository, https://gitlab.com/henrikjstromberg/unitforge

# UnitForge for Python

UnitForge combines physical quantities and unit conversion with a Rust numeric engine. Python 3.10 or newer is required. Install with `pip install unitforge`; NumPy and typing_extensions are dependencies.

```python
from unitforge import Force, ForceUnit, Distance, DistanceUnit, Energy
force = Force(12., ForceUnit.N)
distance = Distance(2., DistanceUnit.m)
intermediate = force * distance
work = intermediate.into_semantic(Energy)
assert work.as_f64() == 24.
assert (force / force).as_f64() == 1.
```

Every multiplication or division with valid dimensions is available, including unnamed intermediates. Operations which are ambiguous in physical meaning produce a generic quantity; `into_energy()`, `into_moment()`, or `into_semantic(NamedClass)` provide explicit interpretation. `into_generic()` erases meaning before reinterpretation.

Named constructors accept the corresponding unit enum. `quantity.to(UnitEnum.variant)` extracts a value in the chosen compatible unit. `as_f64()` explicitly extracts a base-unit float; only Dimensionless accepts `float(quantity)`.

Fixed-shape containers include Vector2/3 and Matrix2/3/2x3/3x2. They support arithmetic, dot/cross products, transposition, norms, determinants, inverses, solving, and rectangular pseudoinverses as appropriate to shape. QR and symmetric eigen decomposition on raw-float Matrix3 use the same Rust algorithms and iteration limits. Quantity vector normalization returns Dimensionless components. NumPy conversion explicitly selects units or extracts raw numeric values.

Static stubs preserve named scalar scaling and explicit interpretation. Products with quantities conservatively return `Quantity`, since arbitrary dimensional expressions cannot be fully represented by finite Python overload tables. Runtime checks enforce dimensions and semantic compatibility.

Downstream Rust extensions exchange versioned data using `unitforge::python_api`; no shared PyO3 class identity is required. Custom quantities are registered using namespaced identities and unit descriptors. See the [API guide](docs/guide.md) for registration, serialization, and the exchange protocol.

