⚡ Physities Performance

Yes, it's slower than raw Python. Here's why that's okay.

🎯 Why Use Physities?

🐛 Catches Bugs at Runtime

Adding meters to seconds? Physities throws an error immediately instead of giving you garbage.

🔄 Automatic Conversions

No more manual "* 1000" or "/ 3600". Convert between km/h and m/s automatically.

📖 Self-Documenting Code

Meter(100) is clearer than 100.0. Your code explains itself.

🚨 The $327 Million Bug

In 1999, NASA's Mars Climate Orbiter crashed because one team used metric units and another used imperial. The software silently did the wrong math.

❌ Plain Python (silent bug)

# Team A sends thrust in pound-seconds
thrust = 4.45  # lb·s

# Team B assumes Newton-seconds
delta_v = thrust / spacecraft_mass
# Wrong by factor of 4.45!
# $327 million spacecraft lost
            

✅ Physities (error caught)

# Team A sends thrust
thrust = PoundForceSecond(4.45)

# Team B's code expects N·s
thrust_ns = thrust.convert(NewtonSecond)
# Automatic conversion!
delta_v = thrust_ns / spacecraft_mass
# Correct calculation ✓
            

⏱️ Performance in Perspective

The overhead is microseconds, not milliseconds.
A single physities operation takes ~2µs. You can do 500,000 operations per second.
For most applications, this is completely negligible compared to I/O, network, or database time.

~2µs

per operation

500K

ops/second

0.002ms

vs 100ms API call

📊 When to Use What

Scenario	Recommendation	Why
Scientific calculations	✅ Physities	Correctness matters more than microseconds
Data pipelines	✅ Physities	I/O dominates; unit bugs are costly
Physics simulations	✅ UnitArray (batch)	Vectorized ops are nearly as fast as NumPy
Real-time graphics	⚠️ Raw Python/NumPy	Every microsecond counts at 60fps
Tight inner loops (10M+ ops)	⚠️ Raw Python/NumPy	Overhead adds up at extreme scale

🚀 Batch Operations (UnitArray)

For many values, use UnitArray for near-NumPy performance:

from physities.src.unit import Meter, Kilometer, UnitArray

# Create array of 10,000 measurements
distances = UnitArray(Meter, sensor_readings)

# Batch operations - vectorized!
km = distances.convert(Kilometer)  # Convert all at once
total = distances.sum()            # ~10µs for 10K elements
avg = distances.mean()
    

📈 Raw Benchmark Data

Object Creation

📉 Performance Trends

Updated on each commit. Raw data · Full documentation