uniUnit
Consistent units manager for Python and the Browser.
Overview
uniUnit is a powerful and flexible library for converting between different unit systems effortlessly. Whether you are working on engineering simulations (FEM), scientific research, or astronomical calculations, uniUnit ensures that your units remain consistent across all your computations.
Key Features
- 🚀 Zero-Latency Conversion: Internal caching for high-performance applications.
- 🛠️ Flexible Mapping: Define custom unit systems with simple dictionaries.
- 📦 Rich Presets: Built-in support for SI, CGS, MKS, Imperial, and common FEM systems.
- 🌏 i18n Support: First-class support for Chinese unit names.
- 🧪 NumPy Integration: Native support for NumPy arrays and batch processing.
- 🌐 Web Dashboard: Includes a client-side browser engine and a FastAPI backend.
Quick Navigation
- 👉 Getting Started: Install the library and run your first conversion in 2 minutes.
- 📖 User Guide: Deep dive into advanced features, custom units, and engineering workflows.
- 🛠️ API Reference: Detailed technical documentation for all classes and functions.
- 💻 Web & API: Learn about the interactive browser dashboard and FastAPI endpoints.
| English | 中文 |
English README
(The original README content continues below…)
What is uniUnit?
uniUnit is a simple Python library for converting between different unit systems effortlessly. It’s especially useful for engineering calculations and simulations (like FEM) where maintaining unit consistency is crucial.
Installation
pip install pint
Quick Start
from uniunit import unit, uniUnit
# Define target unit system: mm-g-s
conv = {'m': 'mm', 'kg': 'g', 's': 's'}
u = uniUnit(conv)
# Convert 100 kg to grams
u.to_unit(100 * unit.kg) # 100000.0 gram
Core Features
1. Basic Unit Conversion
from uniunit import unit, uniUnit
# Convert to mm-g-s system
u = uniUnit({'m': 'mm', 'kg': 'g', 's': 's'})
# 100 kg → grams
u.to_unit(100 * unit.kg) # 100000.0 gram
# 1 Joule → g·mm²/s²
u.to_unit(1 * unit.J) # 1000000000.0 gram * millimeter ** 2 / second ** 2
# 1 Pascal → g/(mm·s²)
u.to_unit(1 * unit.Pa) # 1.0 gram / millimeter / second ** 2
2. Nano-Science Units
For nano-science researchers:
# nm-μg-ps system
u = uniUnit({'m': 'nm', 'kg': 'ug', 's': 'ps'})
# 2×10¹¹ Pa → μg/(nm·ps²)
u.to_unit(2e11 * unit.Pa) # 2e-13 microgram / nanometer / picosecond ** 2
3. Imperial Units
Convert to British/imperial units:
# pound-inch-minute system
u = uniUnit({'m': 'inch', 'kg': 'pound', 's': 'min'})
# 1 W/m² → pound/(inch·min³)
u.to_unit(unit('1 W/m^2')) # 476198.4863193356 pound / minute ** 3
4. Built-in Presets
One-line unit system switching:
from uniunit import quick_convert, UnitSystem
# Quick conversion
quick_convert(100 * unit.kg, 'SI', 'CGS') # 1000.0 gram
quick_convert(1 * unit.m, 'SI', 'Imperial') # 39.37 inch
# Use presets
cgs = UnitSystem.get_preset('CGS')
cgs.to_unit(1 * unit.kg) # 1000.0 gram
cgs.to_unit(1 * unit.m) # 100.0 centimeter
Available presets: SI, MKS, CGS, mmkgms, mmgms, nm_ug_ps, Imperial, FPS, British
5. Chinese Units Support
Use Chinese unit names directly:
# Chinese units
u = uniUnit({'m': '米', 'kg': '千克', 's': '秒'})
u.to_unit(1 * unit.km) # 1000.0 米
u.to_unit(1000 * unit.g) # 1.0 千克
# Extended Chinese units
u2 = uniUnit({'m': '公分', 's': '刻钟'})
u2.to_unit(1 * unit.m) # 100.0 centimeter
u2.to_unit(1 * unit.hour) # 4.0 15 * minute
6. Light-Based Distance Units
Astronomical units based on speed of light:
u = uniUnit({'m': 'm'})
u.to_unit(1 * unit.light_second) # 299792458 meter
u.to_unit(1 * unit.light_minute) # 17987547480 meter
7. NumPy Support
Batch conversion for arrays:
import numpy as np
from uniunit import unit, uniUnit
u = uniUnit({'m': 'mm', 'kg': 'g', 's': 's'})
# Convert NumPy arrays
distances = np.array([1, 2, 3]) * unit.m
result = u.to_unit(distances)
print(result) # [1000. 2000. 3000.] gram
# Works with lists too
values = [1, 2, 3] * unit.kg
result = u.to_unit(values)
print(result) # [1000. 2000. 3000.] gram
8. Performance Optimization
The library includes internal caching for repeated conversions:
u = uniUnit({'m': 'mm', 'kg': 'g', 's': 'ms'})
# First call computes and caches
result1 = u.to_unit(1 * unit.m)
# Subsequent calls use cache
result2 = u.to_unit(1 * unit.kg)
result3 = u.to_unit(1 * unit.s)
More Use Cases
FEM Simulation
from uniunit import unit, uniUnit, UnitSystem
# Common FEM unit system: mm-kg-ms
fem = UnitSystem.get_preset('mmkgms')
# Convert simulation results
pressure = fem.to_unit(1000 * unit.Pa)
# 0.001 kilogram / millimeter / millisecond ** 2
velocity = fem.to_unit(50 * unit.m / unit.s)
# 50.0 millimeter / millisecond
acceleration = fem.to_unit(9.8 * unit.m / unit.s**2)
# 9.8e-3 millimeter / millisecond ** 2
Custom Unit Systems
from uniunit import ureg, uniUnit
# Define custom units
ureg.define('Long = 1000 * kilometer') # Custom length
ureg.define('Flash = 1 * millisecond') # Custom time
# Use in conversion
u = uniUnit({'m': 'Long', 's': 'Flash'})
u.to_unit(9.8 * unit.m / unit.s**2)
# 9.8e-12 Long / Flash ** 2
Multi-Physics Calculations
# Mechanical + Thermal
u = uniUnit({'m': 'cm', 'kg': 'g', 's': 's', 'K': 'K'})
# Stress
stress = u.to_unit(100 * unit.Pa) # 1000.0 gram / centimeter / second ** 2
# Thermal conductivity
k = u.to_unit(150 * unit.W / unit.m / unit.K)
# 15000000.0 gram * centimeter / second ** 3 / kelvin
Helper Functions
from uniunit import get_base_unit, get_unit_info, check_unit_compatibility
# Get base dimensions
get_base_unit(unit.Pa)
# {'[mass]': 1, '[length]': -1, '[time]': -2}
# Get detailed unit info
get_unit_info(100 * unit.kg)
# {'magnitude': 100, 'units': 'kilogram', 'base_units': {'[mass]': 1}, ...}
# Check compatibility
check_unit_compatibility(unit.kg, unit.g) # True
check_unit_compatibility(unit.kg, unit.m) # False
Unit Access Methods
from uniunit import unit, ureg
# Method 1: unit prefix (recommended)
unit.kg, unit.m, unit.s, unit.J
# Method 2: ureg
ureg.kg, ureg.m, ureg.s
# Method 3: string
unit('100 kg'), unit('50 m/s')
中文
uniUnit 是什么？
uniUnit 是一个简洁的 Python 单位转换库，帮助你在不同单位制之间轻松转换。特别适用于工程计算和仿真（如 FEM），保持单位一致性非常重要。
安装
pip install pint
快速开始
from uniunit import unit, uniUnit
# 定义目标单位制: 毫米-克-秒
conv = {'m': 'mm', 'kg': 'g', 's': 's'}
u = uniUnit(conv)
# 转换 100 kg → grams
u.to_unit(100 * unit.kg) # 100000.0 gram
核心功能
1. 基本单位转换
from uniunit import unit, uniUnit
# 转换为毫米-克-秒单位制
u = uniUnit({'m': 'mm', 'kg': 'g', 's': 's'})
# 100 kg → grams
u.to_unit(100 * unit.kg) # 100000.0 gram
# 1 Joule → g·mm²/s²
u.to_unit(1 * unit.J) # 1000000000.0 gram * millimeter ** 2 / second ** 2
# 1 Pascal → g/(mm·s²)
u.to_unit(1 * unit.Pa) # 1.0 gram / millimeter / second ** 2
2. 纳米科学单位
纳米科学研究人员常用：
# 纳米-微克-皮秒单位制
u = uniUnit({'m': 'nm', 'kg': 'ug', 's': 'ps'})
# 2×10¹¹ Pa → μg/(nm·ps²)
u.to_unit(2e11 * unit.Pa) # 2e-13 microgram / nanometer / picosecond ** 2
3. 英制单位
转换为英制单位：
# 磅-英寸-分钟单位制
u = uniUnit({'m': 'inch', 'kg': 'pound', 's': 'min'})
# 1 W/m² → pound/(inch·min³)
u.to_unit(unit('1 W/m^2')) # 476198.4863193356 pound / minute ** 3
4. 预设单位制
内置常用单位制，一行切换：
from uniunit import quick_convert, UnitSystem
# 快速转换
quick_convert(100 * unit.kg, 'SI', 'CGS') # 1000.0 gram
quick_convert(1 * unit.m, 'SI', 'Imperial') # 39.37 inch
# 使用预设
cgs = UnitSystem.get_preset('CGS')
cgs.to_unit(1 * unit.kg) # 1000.0 gram
cgs.to_unit(1 * unit.m) # 100.0 centimeter
可用预设: SI, MKS, CGS, mmkgms, mmgms, nm_ug_ps, Imperial, FPS, British
5. 中文单位支持
支持直接使用中文单位：
# 使用中文单位
u = uniUnit({'m': '米', 'kg': '千克', 's': '秒'})
u.to_unit(1 * unit.km) # 1000.0 米
u.to_unit(1000 * unit.g) # 1.0 千克
6. 光时单位
基于光速的天文距离单位：
u = uniUnit({'m': 'm'})
u.to_unit(1 * unit.light_second) # 299792458 meter
u.to_unit(1 * unit.light_minute) # 17987547480 meter
7. NumPy 支持
批量转换数组：
import numpy as np
from uniunit import unit, uniUnit
u = uniUnit({'m': 'mm', 'kg': 'g', 's': 's'})
# 转换 NumPy 数组
distances = np.array([1, 2, 3]) * unit.m
result = u.to_unit(distances)
print(result) # [1000. 2000. 3000.] gram
# 列表也可以
values = [1, 2, 3] * unit.kg
result = u.to_unit(values)
print(result) # [1000. 2000. 3000.] gram
更多使用场景
FEM 仿真
from uniunit import unit, uniUnit, UnitSystem
# 常用 FEM 单位制: mm-kg-ms
fem = UnitSystem.get_preset('mmkgms')
# 转换仿真结果
pressure = fem.to_unit(1000 * unit.Pa)
# 0.001 kilogram / millimeter / millisecond ** 2
velocity = fem.to_unit(50 * unit.m / unit.s)
# 50.0 millimeter / millisecond
acceleration = fem.to_unit(9.8 * unit.m / unit.s**2)
# 9.8e-3 millimeter / millisecond ** 2
自定义单位系统
from uniunit import ureg, uniUnit
# 定义自定义单位
ureg.define('Long = 1000 * kilometer') # 自定义长度
ureg.define('Flash = 1 * millisecond') # 自定义时间
# 在转换中使用
u = uniUnit({'m': 'Long', 's': 'Flash'})
u.to_unit(9.8 * unit.m / unit.s**2)
# 9.8e-12 Long / Flash ** 2
多物理场计算
# 机械 + 热力学
u = uniUnit({'m': 'cm', 'kg': 'g', 's': 's', 'K': 'K'})
# 应力
stress = u.to_unit(100 * unit.Pa) # 1000.0 gram / centimeter / second ** 2
# 热导率
k = u.to_unit(150 * unit.W / unit.m / unit.K)
# 15000000.0 gram * centimeter / second ** 3 / kelvin
辅助函数
from uniunit import get_base_unit, get_unit_info, check_unit_compatibility
# 获取基本维度
get_base_unit(unit.Pa)
# {'[mass]': 1, '[length]': -1, '[time]': -2}
# 获取单位详细信息
get_unit_info(100 * unit.kg)
# {'magnitude': 100, 'units': 'kilogram', 'base_units': {'[mass]': 1}, ...}
# 检查兼容性
check_unit_compatibility(unit.kg, unit.g) # True
check_unit_compatibility(unit.kg, unit.m) # False
单位访问方式
from uniunit import unit, ureg
# 方式1: unit 前缀 (推荐)
unit.kg, unit.m, unit.s, unit.J
# 方式2: ureg
ureg.kg, ureg.m, ureg.s
# 方式3: 字符串
unit('100 kg'), unit('50 m/s')
API Reference | API 参考
1. Unit Conversion | 单位转换
from uniunit import uniUnit, convert_value
# 使用 uniUnit 类
u = uniUnit({'kg': 'g', 'm': 'mm', 's': 's'})
u.to_unit(100 * ureg.kg) # 100000.0 gram
u.to_unit(1 * ureg.m) # 1000.0 millimeter
# 快速转换
convert_value(100, 'km', 'm') # 100000.0
2. Unit System | 单位系统
from uniunit import UnitSystem, quick_convert
# 使用预设单位制
si = UnitSystem.get_preset('SI')
cgs = UnitSystem.get_preset('CGS')
si.to_unit(1 * ureg.kg) # 1.0 kilogram
cgs.to_unit(1 * ureg.kg) # 1000.0 gram
# 快速转换
quick_convert('100 kg', 'SI', 'CGS') # 100000.0 gram
quick_convert('1 hour', 'SI', 'CGS') # 3600.0 gram * centimeter / second
# 预设列表
UnitSystem.list_presets() # ['SI', 'MKS', 'CGS', 'mmkgms', 'mmgms', 'nm_ug_ps', 'Imperial', 'FPS', 'British']
3. Unit Access | 单位访问
from uniunit import unit, ureg
# unit 前缀 (推荐)
unit.kg, unit.m, unit.s, unit.J, unit.Pa
unit('100 kg'), unit('50 m/s')
# ureg 直接访问
ureg.kg, ureg.m, ureg('100 km')
4. Utility Functions | 工具函数
from uniunit import get_base_unit, get_unit_info, check_unit_compatibility
# 获取基本维度
get_base_unit(ureg.Pa) # {'[mass]': 1, '[length]': -1, '[time]': -2}
# 获取单位详细信息
get_unit_info(100 * ureg.kg) # {'magnitude': 100, 'units': 'kilogram', ...}
# 检查兼容性
check_unit_compatibility(ureg.kg, ureg.g) # True
check_unit_compatibility(ureg.kg, ureg.m) # False
# 创建自定义单位
from uniunit import create_custom_unit
create_custom_unit('Long', 1000 * ureg.km)
5. Chinese Units | 中文单位
from uniunit import CHINESE_UNITS, unit
# 支持的中文单位
unit.米, unit.千克, unit.秒
unit.毫米, unit.纳米
unit.摄氏度, unit.华氏度
# 在转换中使用
u = uniUnit({'m': '米', 'kg': '千克', 's': '秒'})
u.to_unit(1 * unit.km) # 1000.0 米
u.to_unit(1000 * unit.g) # 1.0 千克
Module Exports | 模块导出
| Export | Description |
|---|---|
ureg |
Pint UnitRegistry |
unit |
Unit shortcut class |
Quantity |
Pint Quantity |
uniUnit |
Main conversion class |
UnitSystem |
Unit system preset class |
convert_value |
Quick value conversion |
quick_convert |
Convert between presets |
get_base_unit |
Get SI base dimensions |
get_unit_info |
Get detailed unit info |
check_unit_compatibility |
Check if units compatible |
CHINESE_UNITS |
Chinese unit name mappings |