esio-units 0.1.0

Hub-and-spoke unit conversion library for industrial IoT — handles complex conversions with scale, offset, and formula support

esio-units

A high-performance hub-and-spoke unit conversion library for industrial IoT applications, designed to handle complex unit conversions with scale and offset support.

Features

• 🎯 Hub-and-Spoke Pattern: Efficient O(N) conversion system instead of O(N²)
• 🔄 Bidirectional Conversion: Guaranteed round-trip accuracy
• 📊 Scale & Offset Support: Handle device-specific scaling
• 🏭 Industrial Focus: Units for oil & gas, manufacturing, utilities
• ⚡ High Performance: Optimized for IoT telemetry processing
• 🛡️ Type Safe: Full type hints and validation

Why Hub-and-Spoke?

Traditional unit conversion libraries require N×(N-1) conversion functions for N units. Our hub-and-spoke pattern requires only 2N functions, making it much more maintainable and extensible.

Traditional: °F↔°C, °F↔K, °F↔°R, °C↔K, °C↔°R, K↔°R = 6 functions for 4 units
Hub-and-Spoke: °F↔K, °C↔K, °R↔K = 6 functions (3×2) for 4 units
Adding °Ra: Traditional needs +4 functions, Hub-and-spoke needs +2

Installation

pip install esio-units

Quick Start

from esio_units import convert, convert_with_scale

# Simple conversion
celsius = 25.0
fahrenheit = convert(celsius, 'degC', 'degF')
print(f"{celsius}°C = {fahrenheit}°F")  # 25.0°C = 77.0°F

# With scale and offset (device reports 0-100 for -50°C to +150°C)
device_value = 50  # Mid-scale
actual_celsius = convert_with_scale(
    value=device_value,
    from_unit='percent',
    to_unit='degC',
    from_scale=(0, 100),
    to_scale=(-50, 150)
)
print(f"Device {device_value}% = {actual_celsius}°C")  # Device 50% = 50.0°C

# Round-trip verification
original = 100.5
converted = convert(original, 'psi', 'bar')
back = convert(converted, 'bar', 'psi')
print(f"Round-trip: {original} → {converted} → {back}")
# Round-trip: 100.5 → 6.929 → 100.5

Supported Categories

Temperature

• Hub: Kelvin (K)
• Units: K, °C (degC), °F (degF), °R (degR)

Pressure

• Hub: Pascal (Pa)
• Units: Pa, kPa, MPa, bar, psi, atm, mmHg, inHg

Length

• Hub: Meter (m)
• Units: m, km, cm, mm, ft, in, mi, yd

Mass

• Hub: Kilogram (kg)
• Units: kg, g, mg, lb, oz, ton, metric_ton

Volume

• Hub: Cubic Meter (m³)
• Units: m3, L, mL, gal, ft3, bbl, cf

Flow Rate

• Hub: Cubic Meter per Second (m³/s)
• Units: m3/s, L/s, L/min, gpm, cfm, bbl/day

Power

• Hub: Watt (W)
• Units: W, kW, MW, hp, BTU/h

Energy

• Hub: Joule (J)
• Units: J, kJ, MJ, kWh, BTU, cal

Dimensionless

• Hub: Ratio (0-1)
• Units: ratio, percent, ppm, ppb

Advanced Usage

Custom Scale Conversions

from esio_units import ScaleConverter

# Device outputs 4-20mA for 0-100 psi
converter = ScaleConverter(
    from_unit='mA',
    to_unit='psi',
    from_range=(4, 20),
    to_range=(0, 100)
)

current = 12  # mA
pressure = converter.convert(current)
print(f"{current}mA = {pressure} psi")  # 12mA = 50.0 psi

Unit Registry

from esio_units import UnitRegistry

registry = UnitRegistry()

# Get all units in a category
temp_units = registry.get_category_units('temperature')
print(f"Temperature units: {temp_units}")

# Get hub unit for category
hub = registry.get_hub_unit('pressure')
print(f"Pressure hub: {hub}")  # Pressure hub: Pa

# Check if conversion is possible
can_convert = registry.can_convert('degC', 'psi')
print(f"Can convert °C to PSI: {can_convert}")  # False

Validation

from esio_units import validate_conversion

# Check if conversion is valid
is_valid = validate_conversion('degF', 'degC')  # True
is_invalid = validate_conversion('degF', 'kg')  # False

# Get conversion path
from esio_units import get_conversion_path

path = get_conversion_path('psi', 'bar')
print(f"Conversion path: {path}")
# Conversion path: ['psi', 'Pa', 'bar']

Performance

The library is optimized for high-throughput telemetry processing:

• Conversion functions are cached after first use
• No string parsing in hot paths
• Minimal object allocation
• Thread-safe for concurrent processing

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=esio_units

# Run specific category tests
pytest tests/test_temperature.py

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE file for details

Acknowledgments

Built for the EdgeStack IoT platform to provide reliable, efficient unit conversions for industrial telemetry data.