Advanced Features Guide¶
This guide covers the enhanced features of PyQuantity, including expanded unit systems, contextual measurements, and natural language parsing.
Table of Contents¶
Enhanced Unit Systems¶
PyQuantity now supports a comprehensive set of units and dimensions beyond the basic SI units.
Expanded Base Dimensions¶
from pyquantity import Dimension
# All available dimensions:
Dimension.LENGTH # Length
Dimension.MASS # Mass
Dimension.TIME # Time
Dimension.ELECTRIC_CURRENT # Electric current
Dimension.TEMPERATURE # Temperature
Dimension.AMOUNT_OF_SUBSTANCE # Amount of substance
Dimension.LUMINOUS_INTENSITY # Luminous intensity
Dimension.ANGLE # Plane angle
Dimension.SOLID_ANGLE # Solid angle
Dimension.FREQUENCY # Frequency
Dimension.FORCE # Force
Dimension.PRESSURE # Pressure
Dimension.ENERGY # Energy
Dimension.POWER # Power
Dimension.ELECTRIC_CHARGE # Electric charge
Dimension.ELECTRIC_POTENTIAL # Electric potential
Dimension.CAPACITANCE # Capacitance
Dimension.RESISTANCE # Resistance
Dimension.CONDUCTANCE # Conductance
Dimension.MAGNETIC_FLUX # Magnetic flux
Dimension.MAGNETIC_FLUX_DENSITY # Magnetic flux density
Dimension.INDUCTANCE # Inductance
Dimension.LUMINOUS_FLUX # Luminous flux
Dimension.ILLUMINANCE # Illuminance
Dimension.RADIOACTIVITY # Radioactivity
Dimension.ABSORBED_DOSE # Absorbed dose
Dimension.EQUIVALENT_DOSE # Equivalent dose
Dimension.CATALYTIC_ACTIVITY # Catalytic activity
Comprehensive Derived Units¶
Mechanical Units¶
# Speed and velocity
speed = Quantity(25.0, "meter/second")
speed_kmh = speed.convert("kilometer/hour") # ~90 km/h
# Acceleration
acceleration = Quantity(9.81, "meter/second_squared") # Gravity
# Area
area = Quantity(25.0, "square_meter")
# Volume
volume = Quantity(1.0, "cubic_meter")
volume_liters = volume.convert("liter") # 1000 liters
# Pressure
pressure = Quantity(101325.0, "pascal")
pressure_atm = pressure.convert("atmosphere") # 1 atm
# Energy
energy = Quantity(1000.0, "joule")
energy_cal = energy.convert("calorie") # ~239 cal
# Power
power = Quantity(100.0, "watt")
power_hp = power.convert("horsepower") # ~0.134 hp
Electrical Units¶
# Voltage
voltage = Quantity(230.0, "volt")
voltage_mv = voltage.convert("millivolt") # 230000 mV
# Current
current = Quantity(10.0, "ampere")
current_ma = current.convert("milliampere") # 10000 mA
# Resistance
resistance = Quantity(470.0, "ohm")
resistance_kohm = resistance.convert("kiloohm") # 0.47 kΩ
# Capacitance
capacitance = Quantity(100.0, "microfarad")
capacitance_f = capacitance.convert("farad") # 0.0001 F
# Inductance
inductance = Quantity(10.0, "millihenry")
inductance_h = inductance.convert("henry") # 0.01 H
# Frequency
frequency = Quantity(50.0, "hertz")
frequency_khz = frequency.convert("kilohertz") # 0.05 kHz
Thermal Units¶
# Temperature
temp_c = Quantity(25.0, "celsius")
temp_f = Quantity(77.0, "fahrenheit")
temp_k = Quantity(298.15, "kelvin")
# Specific heat
specific_heat = Quantity(4186.0, "joule/kilogram/kelvin") # Water
# Thermal conductivity
conductivity = Quantity(0.6, "watt/meter/kelvin") # Typical insulator
Optical Units¶
# Luminous flux
luminous_flux = Quantity(1000.0, "lumen")
# Illuminance
illuminance = Quantity(500.0, "lux")
SI Prefixes¶
PyQuantity supports the full range of SI prefixes from yocto (10^-24) to yotta (10^24):
# Large prefixes
distance = Quantity(1.0, "kilometer") # 10^3 meters
distance = Quantity(1.0, "megameter") # 10^6 meters
distance = Quantity(1.0, "gigameter") # 10^9 meters
distance = Quantity(1.0, "terameter") # 10^12 meters
distance = Quantity(1.0, "petameter") # 10^15 meters
# Small prefixes
distance = Quantity(1.0, "millimeter") # 10^-3 meters
distance = Quantity(1.0, "micrometer") # 10^-6 meters
distance = Quantity(1.0, "nanometer") # 10^-9 meters
distance = Quantity(1.0, "picometer") # 10^-12 meters
distance = Quantity(1.0, "femtometer") # 10^-15 meters
distance = Quantity(1.0, "attometer") # 10^-18 meters
# Electrical prefixes
voltage = Quantity(1.0, "millivolt") # 10^-3 volts
voltage = Quantity(1.0, "microvolt") # 10^-6 volts
voltage = Quantity(1.0, "nanovolt") # 10^-9 volts
current = Quantity(1.0, "microampere") # 10^-6 amperes
current = Quantity(1.0, "nanoampere") # 10^-9 amperes
resistance = Quantity(1.0, "kiloohm") # 10^3 ohms
resistance = Quantity(1.0, "megaohm") # 10^6 ohms
Unit Conversion Examples¶
# Speed conversions
speed_mph = Quantity(60.0, "mile/hour")
speed_mps = speed_mph.convert("meter/second") # ~26.82 m/s
speed_kmh = speed_mph.convert("kilometer/hour") # ~96.56 km/h
# Pressure conversions
pressure_psi = Quantity(14.7, "psi")
pressure_pa = pressure_psi.convert("pascal") # ~101325 Pa
pressure_bar = pressure_psi.convert("bar") # ~1.01325 bar
# Volume conversions
volume_gal = Quantity(1.0, "gallon")
volume_l = volume_gal.convert("liter") # ~3.785 L
volume_ml = volume_gal.convert("milliliter") # ~3785 mL
# Energy conversions
energy_kwh = Quantity(1.0, "kilowatt_hour")
energy_j = energy_kwh.convert("joule") # 3,600,000 J
energy_cal = energy_kwh.convert("kilocalorie") # ~860 kcal
Contextual Measurements¶
PyQuantity includes a database of real-world objects with standard measurements.
Using the Measurement Database¶
from pyquantity import MeasurementDatabase, get_measurement
# Create database instance
db = MeasurementDatabase()
# Get standard measurements
bath = db.get_measurement("normal bath")
print(f"Normal bath: {bath}") # 150.0 liter
cup = db.get_measurement("cup")
print(f"Standard cup: {cup}") # 250.0 milliliter
# Calculate how many cups in a bath
cups_in_bath = bath / cup
print(f"Cups in a bath: {cups_in_bath:.1f}") # ~600.0
Available Measurement Categories¶
Volume Measurements¶
# Small volumes
teaspoon = get_measurement("teaspoon") # 5 mL
tablespoon = get_measurement("tablespoon") # 15 mL
cup = get_measurement("cup") # 250 mL
glass = get_measurement("glass") # 200 mL
# Medium volumes
bottle = get_measurement("bottle") # 500 mL
can = get_measurement("can") # 330 mL
jug = get_measurement("jug") # 1 L
bucket = get_measurement("bucket") # 10 L
# Large volumes
bathtub = get_measurement("bathtub") # 150 L
normal_bath = get_measurement("normal bath") # 150 L
swimming_pool = get_measurement("swimming pool") # 50,000 L
ocean = get_measurement("ocean") # 1.332e21 L
Mass Measurements¶
grain_of_salt = get_measurement("grain of salt") # 0.06 mg
paperclip = get_measurement("paperclip") # 1 g
apple = get_measurement("apple") # 150 g
loaf_of_bread = get_measurement("loaf of bread") # 500 g
bag_of_sugar = get_measurement("bag of sugar") # 1 kg
average_person = get_measurement("average person") # 70 kg
car = get_measurement("car mass") # 1500 kg
elephant = get_measurement("elephant") # 5000 kg
blue_whale = get_measurement("blue whale") # 150,000 kg
Length Measurements¶
grain_of_sand = get_measurement("grain of sand") # 0.5 mm
credit_card = get_measurement("credit card") # 85.6 mm
smartphone = get_measurement("smartphone") # 150 mm
pizza = get_measurement("pizza") # 30 cm
door = get_measurement("door") # 2 m
room = get_measurement("room") # 5 m
football_field = get_measurement("football field length") # 100 m
marathon = get_measurement("marathon") # 42.195 km
mount_everest = get_measurement("mount everest") # 8848 m
Speed Measurements¶
snail = get_measurement("snail") # 0.05 m/s
walking = get_measurement("walking") # 1.4 m/s
running = get_measurement("running") # 5.0 m/s
cycling = get_measurement("cycling") # 7.0 m/s
car = get_measurement("car speed") # 25.0 m/s
high_speed_train = get_measurement("high speed train") # 83.0 m/s
airplane = get_measurement("airplane") # 250.0 m/s
speed_of_sound = get_measurement("speed of sound") # 343.0 m/s
speed_of_light = get_measurement("speed of light") # 299,792,458 m/s
Custom Measurements¶
# Create custom database
db = MeasurementDatabase()
# Add custom measurements
db.add_measurement("my coffee mug", Quantity(350.0, "milliliter"))
db.add_measurement("my commute", Quantity(15.0, "kilometer"))
db.add_measurement("my workspace", Quantity(10.0, "square_meter"))
# Retrieve custom measurements
mug = db.get_measurement("my coffee mug")
commute = db.get_measurement("my commute")
workspace = db.get_measurement("my workspace")
print(f"My coffee mug: {mug}")
print(f"My commute distance: {commute}")
print(f"My workspace area: {workspace}")
Searching Measurements¶
# Search for measurements containing specific terms
bath_results = db.find_measurements("bath")
print("Measurements containing 'bath':")
for name, quantity in bath_results:
print(f" {name}: {quantity}")
# Search for speed-related measurements
speed_results = db.find_measurements("speed")
print("Speed-related measurements:")
for name, quantity in speed_results:
print(f" {name}: {quantity}")
Natural Language Parsing¶
PyQuantity can extract quantities and units from natural language text.
Parsing Individual Quantities¶
from pyquantity import parse_quantity
# Parse simple quantities
qty1 = parse_quantity("5 meters")
print(qty1) # 5.0 meter
qty2 = parse_quantity("100 km/h")
print(qty2) # 100.0 kilometer/hour
qty3 = parse_quantity("2.5 kilograms")
print(qty3) # 2.5 kilogram
qty4 = parse_quantity("150 liters")
print(qty4) # 150.0 liter
Extracting Multiple Quantities¶
from pyquantity import extract_quantities
text = "A car traveling at 120 km/h for 2.5 hours consumes 30 liters of fuel."
quantities = extract_quantities(text)
print(f"Found {len(quantities)} quantities:")
for i, qty in enumerate(quantities, 1):
print(f" {i}. {qty}")
Finding Units in Text¶
from pyquantity import find_units_in_text
text = "The pressure is 1013 hPa and temperature is 25°C with humidity at 60%."
units = find_units_in_text(text)
print(f"Found {len(units)} units:")
for unit in units:
print(f" - {unit}")
Contextual Object Recognition¶
text = "I filled the bathtub and it took 15 minutes to fill."
# The parser can recognize "bathtub" as a known object with standard volume
# Find objects in text
objects_found = []
for object_name, quantity in db.measurements.items():
if object_name in text.lower():
objects_found.append((object_name, quantity))
print("Recognized objects:")
for name, qty in objects_found:
print(f" {name}: {qty}")
Advanced Parsing Examples¶
# Complex units
complex_text = "The acceleration is 9.81 m/s² and pressure is 101.325 kPa"
quantities = extract_quantities(complex_text)
# Scientific notation
scientific_text = "The capacitance is 1e-6 F and resistance is 4.7e3 Ω"
quantities = extract_quantities(scientific_text)
# Mixed units
mixed_text = "Speed: 60 mph, Distance: 100 km, Time: 2.5 hours"
quantities = extract_quantities(mixed_text)
Advanced Physics Calculations¶
Kinematics¶
# distance = speed × time
speed = Quantity(25.0, "meter/second")
time = Quantity(10.0, "second")
distance = speed * time
print(f"Distance: {distance}") # 250.0 meter/second*second
# acceleration = (final_velocity - initial_velocity) / time
initial_velocity = Quantity(0.0, "meter/second")
final_velocity = Quantity(10.0, "meter/second")
time = Quantity(5.0, "second")
acceleration = (final_velocity - initial_velocity) / time
print(f"Acceleration: {acceleration}") # 2.0 meter/second/second
Dynamics¶
# force = mass × acceleration
mass = Quantity(10.0, "kilogram")
acceleration = Quantity(9.81, "meter/second_squared")
force = mass * acceleration
print(f"Force: {force}") # 98.1 kilogram*meter/second_squared (newton)
# power = force × velocity
velocity = Quantity(5.0, "meter/second")
power = force * velocity
print(f"Power: {power}") # 490.5 kilogram*meter²/second³ (watt)
# work = force × distance
work = force * distance
print(f"Work: {work}") # 2452.5 kilogram*meter²/second² (joule)
Energy Calculations¶
# kinetic energy = 0.5 × mass × velocity²
mass = Quantity(1000.0, "kilogram") # 1000 kg car
velocity = Quantity(25.0, "meter/second") # ~90 km/h
kinetic_energy = 0.5 * mass * (velocity ** 2)
print(f"Kinetic energy: {kinetic_energy}") # 312500.0 kilogram*meter²/second²
# Convert to kilowatt-hours
energy_kwh = kinetic_energy.convert("kilowatt_hour")
print(f"Energy in kWh: {energy_kwh}") # ~0.0868 kWh
# potential energy = mass × gravity × height
height = Quantity(10.0, "meter")
gravity = Quantity(9.81, "meter/second_squared")
potential_energy = mass * gravity * height
print(f"Potential energy: {potential_energy}") # 98100.0 kilogram*meter²/second²
Electrical Engineering¶
# Ohm's Law: V = I × R
current = Quantity(2.0, "ampere")
resistance = Quantity(50.0, "ohm")
voltage = current * resistance
print(f"Voltage: {voltage}") # 100.0 ampere*ohm (volt)
# Power: P = V × I
power = voltage * current
print(f"Power: {power}") # 200.0 ampere*ohm*ampere (watt)
# Energy: E = P × t
energy = power * Quantity(10.0, "second")
print(f"Energy: {energy}") # 2000.0 ampere*ohm*ampere*second (joule)
# RC time constant: τ = R × C
resistance = Quantity(1000.0, "ohm")
capacitance = Quantity(100.0, "microfarad")
time_constant = resistance * capacitance
print(f"Time constant: {time_constant}") # 0.1 ohm*farad (second)
Thermodynamics¶
# Heat transfer: Q = m × c × ΔT
mass = Quantity(1.0, "kilogram") # 1 kg water
specific_heat = Quantity(4186.0, "joule/kilogram/kelvin")
temp_change = Quantity(10.0, "kelvin")
heat_energy = mass * specific_heat * temp_change
print(f"Heat energy: {heat_energy}") # 41860.0 joule
# Heat transfer rate: Q/t
heat_power = heat_energy / Quantity(60.0, "second")
print(f"Heat power: {heat_power}") # ~697.67 watt
Practical Applications¶
Cooking and Recipes¶
# Convert recipe measurements
flour_cups = Quantity(2.5, "cup")
flour_ml = flour_cups.convert("milliliter")
print(f"2.5 cups of flour = {flour_ml}") # 625.0 milliliter
# How many tablespoons in a cup?
cup = get_measurement("cup")
tablespoon = get_measurement("tablespoon")
tbsp_per_cup = cup / tablespoon
print(f"Tablespoons per cup: {tbsp_per_cup}") # 16.666...
# Calculate total recipe volume
sugar = Quantity(1.0, "cup")
flour = Quantity(2.5, "cup")
butter = Quantity(0.5, "cup")
total_volume = sugar + flour + butter
print(f"Total volume: {total_volume}") # 4.0 cup
Home Energy Usage¶
# Calculate appliance energy consumption
light_bulb = get_measurement("light bulb") # 60 W
hours_per_day = Quantity(6.0, "hour")
days_per_year = 365
daily_energy = light_bulb * hours_per_day
annual_energy = daily_energy * days_per_year
annual_energy_kwh = annual_energy.convert("kilowatt_hour")
print(f"Annual energy for one light bulb: {annual_energy_kwh}") # ~131.4 kWh
# Calculate cost
energy_price = Quantity(0.15, "dollar/kilowatt_hour")
annual_cost = annual_energy_kwh * energy_price
print(f"Annual cost: {annual_cost}") # ~19.71 dollar
Fitness and Health¶
# Calculate calorie expenditure
running_speed = get_measurement("running") # ~5 m/s
# Approximate MET calculation
met_value = 8.0 # Running MET value
person_mass = get_measurement("average person") # 70 kg
time = Quantity(1.0, "hour")
calories_burned = (met_value * person_mass.value * time.value) * Quantity(1.0, "kilocalorie")
print(f"Calories burned running for 1 hour: {calories_burned}") # ~560 kcal
# Calculate running distance
distance = running_speed * time
distance_km = distance.convert("kilometer")
print(f"Distance run: {distance_km}") # ~18 km
Engineering Applications¶
# Structural engineering - stress calculation
force = Quantity(10000.0, "newton")
area = Quantity(0.1, "square_meter")
stress = force / area
stress_pa = stress.convert("pascal")
print(f"Stress: {stress_pa}") # 100000.0 pascal
# Fluid dynamics - flow rate
volume = Quantity(100.0, "liter")
time = Quantity(10.0, "second")
flow_rate = volume / time
flow_rate_lps = flow_rate.convert("liter/second")
print(f"Flow rate: {flow_rate_lps}") # 10.0 liter/second
# Electrical engineering - circuit power
voltage = Quantity(230.0, "volt")
current = Quantity(5.0, "ampere")
power = voltage * current
power_kw = power.convert("kilowatt")
print(f"Circuit power: {power_kw}") # 1.15 kilowatt
Best Practices¶
Use Standard Units: Prefer base units (meter, kilogram, second) for calculations
Convert Early: Convert to desired units before complex calculations
Handle Exceptions: Always catch ValueError for invalid operations
Use Context: Provide context in text for better parsing accuracy
Check Dimensions: Verify dimensional compatibility before operations
Leverage Contextual Data: Use the measurement database for real-world comparisons
Parse Strategically: Use natural language parsing for user input, direct Quantity creation for code
Performance Considerations¶
Quantity creation is fast and lightweight
Unit conversion involves dimensional analysis which is O(n) where n is number of dimensions
Parsing performance depends on text length and quantity density
For bulk operations, consider caching Quantity objects
The measurement database uses dictionary lookups for O(1) access
Development and Release Process¶
Creating Releases¶
PyQuantity uses GitHub Releases to distribute pre-built wheel files. Here’s how to create a new release:
# 1. Update the version in pyproject.toml
# 2. Commit your changes
git add .
git commit -m "Prepare release v1.0.0"
# 3. Create an annotated tag
git tag -a v1.0.0 -m "Release v1.0.0"
# 4. Push the tag to trigger the release workflow
git push origin v1.0.0
The GitHub Actions release workflow will automatically:
Build the source distribution and wheel files
Create a GitHub Release with the tag name
Upload the wheel and source files as release assets
Accessing Release Artifacts¶
From GitHub Releases:
# Download from the releases page
wget https://github.com/odysseu/pyquantity/releases/download/v1.0.0/pyquantity-1.0.0-py3-none-any.whl
pip install pyquantity-1.0.0-py3-none-any.whl
From CI Artifacts (for development builds):
# Download the latest CI artifact
# Go to: https://github.com/odysseu/pyquantity/actions
# Download "python-package-distributions" artifact from the latest successful run
unzip python-package-distributions.zip
pip install *.whl
Future Enhancements¶
The following features are planned for future releases:
Temperature Unit Conversions: Full support for Celsius, Fahrenheit, Kelvin conversions
Currency Support: Integration with exchange rate APIs
Custom Unit Systems: User-defined unit systems and conversions
Enhanced NLP: More sophisticated natural language understanding
Unit Inference: Automatic unit detection from context
Measurement Learning: System that learns new object measurements from usage
Contextual Calculations: Automatic calculation of derived quantities from text
Visualization: Integration with plotting libraries for quantity visualization