dimtensor catches dimensional errors at operation time, not after hours of computation.

from dimtensor import DimArray, units

# Operations check dimensions automatically
velocity = DimArray([10, 20, 30], units.m / units.s)
time = DimArray([1, 2, 3], units.s)
distance = velocity * time  # [10 40 90] m

# Errors caught immediately
acceleration = DimArray([9.8], units.m / units.s**2)
velocity + acceleration  # DimensionError: cannot add m/s to m/s^2

Why dimtensor?

Features

• Dimensional Safety - Operations between incompatible dimensions raise DimensionError
• Unit Conversion - Convert between compatible units with .to()
• NumPy/PyTorch/JAX - Full integration with all three frameworks
• Physical Constants - CODATA 2022 constants with proper units and uncertainties
• Uncertainty Propagation - Track and propagate measurement uncertainties
• I/O Support - JSON, HDF5, Parquet, NetCDF, pandas, xarray
• Visualization - Matplotlib and Plotly with automatic unit labels
• Domain Units - Astronomy, chemistry, and engineering units
• Dimensional Inference - Infer dimensions from variable names and equations
• Dimensional Linting - Static analysis CLI for finding unit errors
• Optional Rust Backend - Accelerated operations when built from source

Installation

pip install dimtensor

For framework-specific support:

pip install dimtensor[torch]  # PyTorch integration
pip install dimtensor[jax]    # JAX integration
pip install dimtensor[all]    # All optional dependencies

Optional: Rust Backend (v2.0+)

For improved performance, build the optional Rust backend:

# Install Rust (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
pip install maturin

# Build and install the Rust extension
cd /path/to/dimtensor/rust
maturin build --release
pip install target/wheels/dimtensor_core-*.whl

The library automatically uses the Rust backend when available, with a pure Python fallback otherwise. Check availability:

from dimtensor._rust import HAS_RUST_BACKEND
print(f"Rust backend: {HAS_RUST_BACKEND}")

Quick Start

NumPy

from dimtensor import DimArray, units

v = DimArray([10], units.m / units.s)  # velocity
t = DimArray([5], units.s)              # time
d = v * t                               # distance = 50 m

PyTorch

import torch
from dimtensor.torch import DimTensor
from dimtensor import units

# Unit-aware tensors with autograd
v = DimTensor(torch.tensor([1.0, 2.0, 3.0], requires_grad=True), units.m / units.s)
t = DimTensor(torch.tensor([0.5, 1.0, 1.5]), units.s)
d = v * t  # distance in meters

# Gradients flow through
d.sum().backward()
print(v.grad)

# GPU support
v_cuda = v.cuda()

JAX

import jax
import jax.numpy as jnp
from dimtensor.jax import DimArray
from dimtensor import units

@jax.jit
def kinetic_energy(mass, velocity):
    return 0.5 * mass * velocity**2

m = DimArray(jnp.array([1.0, 2.0]), units.kg)
v = DimArray(jnp.array([10.0, 20.0]), units.m / units.s)
E = kinetic_energy(m, v)  # JIT-compiled, units preserved: [50. 400.] J

Physical Constants

from dimtensor import constants, DimArray, units

print(constants.c)   # Speed of light: 299792458.0 m/s
print(constants.h)   # Planck constant with uncertainty

E = constants.c**2 * DimArray([1.0], units.kg)  # E = mc^2

Uncertainty Propagation

from dimtensor import DimArray, units

length = DimArray([10.0], units.m, uncertainty=[0.1])
width = DimArray([5.0], units.m, uncertainty=[0.05])

area = length * width  # 50 +/- 0.71 m^2 (propagated in quadrature)

I/O

from dimtensor import DimArray, units
from dimtensor.io import save_json, load_json, save_hdf5, load_hdf5

arr = DimArray([1.0, 2.0, 3.0], units.m)

# JSON
save_json(arr, "data.json")
loaded = load_json("data.json")  # Units preserved

# HDF5
save_hdf5(arr, "data.h5", compression="gzip")
loaded = load_hdf5("data.h5")

Visualization

from dimtensor import DimArray, units
from dimtensor.visualization import plot

time = DimArray([0, 1, 2, 3], units.s)
distance = DimArray([0, 10, 40, 90], units.m)

plot(time, distance)  # Axes labeled automatically: [s], [m]

Domain-Specific Units

from dimtensor import DimArray
from dimtensor.domains.astronomy import parsec, light_year, solar_mass
from dimtensor.domains.chemistry import molar, dalton
from dimtensor.domains.engineering import MPa, hp, kWh

# Astronomy
distance = DimArray([4.24], light_year).to(parsec)  # ~1.3 pc

# Chemistry
concentration = DimArray([0.1], molar)  # 0.1 M

# Engineering
stress = DimArray([250], MPa)
power = DimArray([100], hp)

Dataset Loaders (v3.3.0+)

from dimtensor.loaders import NistCodataLoader, NasaExoplanetLoader, PrismClimateLoader

# Load NIST CODATA 2022 fundamental constants
loader = NistCodataLoader()
constants_df = loader.load()  # Returns DimArrays with units and uncertainties
print(constants_df['speed_of_light'])  # 299792458.0 m/s (exact)

# Load NASA confirmed exoplanets
exo_loader = NasaExoplanetLoader()
exoplanets = exo_loader.load()  # Orbital parameters with proper units
print(exoplanets['orbital_period'])  # DimArray with unit: days

# Load PRISM climate data for a specific location
climate_loader = PrismClimateLoader(lat=40.7128, lon=-74.0060)  # NYC
data = climate_loader.load(start_date='2020-01-01', end_date='2020-12-31')
print(data['temperature'])  # DimArray with unit: degC
print(data['precipitation'])  # DimArray with unit: mm

# All loaders support caching at ~/.dimtensor/cache/

Dimensional Inference (v2.0+)

from dimtensor.inference import infer_dimension, get_equations_by_domain

# Infer dimension from variable name
result = infer_dimension("velocity")
print(result.dimension)    # L·T⁻¹ (length/time)
print(result.confidence)   # 0.9

# Works with prefixes and suffixes
result = infer_dimension("initial_velocity_x")
print(result.dimension)    # L·T⁻¹

# Query physics equations
mechanics = get_equations_by_domain("mechanics")
for eq in mechanics[:3]:
    print(f"{eq.name}: {eq.formula}")
# Newton's Second Law: F = ma
# Kinetic Energy: KE = ½mv²
# Gravitational Force: F = Gm₁m₂/r²

Automatic Unit Inference (v3.3.0+)

from dimtensor.inference import infer_units
from dimtensor import units

# Infer unknown units from equations
equations = [
    "F = m * a",      # Newton's second law
    "E = F * d"       # Work equation
]
knowns = {
    "m": units.kg,
    "a": units.m / units.s**2,
    "d": units.m
}
unknowns = ["F", "E"]

result = infer_units(equations, knowns, unknowns)
print(result["F"])  # kg·m·s⁻² (newton)
print(result["E"])  # kg·m²·s⁻² (joule)

# Detect dimensional inconsistencies
equations_bad = ["v = a + t"]  # Invalid: cannot add acceleration to time
result = infer_units(equations_bad, {"a": units.m/units.s**2, "t": units.s}, ["v"])
# Raises DimensionError

Dimensional Linting (v2.1+)

# Lint a file for dimensional issues
dimtensor lint physics_simulation.py

# Example output:
# physics.py:15:4: W002 Potential dimension mismatch: LT⁻¹ + LT⁻²
#   velocity + acceleration
#   Suggestion: Cannot add/subtract LT⁻¹ and LT⁻². Check your units.

# JSON output for IDE integration
dimtensor lint --format=json src/

# Strict mode (report all inferences)
dimtensor lint --strict script.py

Useful Links

• Documentation
• Source Code
• Issue Tracker
• Changelog
• PyPI

Call for Contributions

dimtensor is an open source project and welcomes contributions of all kinds. Here are ways to get involved:

• Report bugs - Open an issue
• Request features - Share ideas in discussions
• Contribute code - See our contributing guide
• Improve docs - Fix typos, add examples, clarify explanations
• Share use cases - Write tutorials or blog posts

Writing code isn't the only way to contribute. Good issues, documentation improvements, and community engagement are just as valuable.

License

MIT