Nursing Dosage Calculations

This walkthrough demonstrates dimensional analysis for medication dosing—a domain where unit errors can be fatal.

Each example shows two approaches:

• Python API — Direct use of ucon in your code
• MCP Server — Via AI agents like Claude

Why Dimensional Analysis Matters

Medication errors kill thousands of patients annually. Common mistakes:

• Confusing mg with mcg (1000× error)
• Using lb instead of kg for weight-based dosing (2.2× error)
• Miscalculating IV drip rates

Dimensional analysis catches these errors by tracking units through every step.

---

Weight-Based Dosing

Problem: A 154 lb patient needs a drug dosed at 15 mg/kg/day, given every 8 hours (3 doses/day). What's the dose per administration?

Python API

from ucon import units, Scale

mg = Scale.milli * units.gram
kg = Scale.kilo * units.gram

# Givens as callable units
weight = units.pound(154).to(kg)
dose_rate = (mg / kg / units.day)(15)  # 15 mg per kg per day
doses_per_day = units.each(3) / units.day(1)  # 3 doses per day

# Calculate: weight × dose_rate ÷ doses_per_day
daily_dose = weight * dose_rate
print(daily_dose)  # <1047.6... mg/day>

dose_per_admin = daily_dose / doses_per_day
print(dose_per_admin)  # <349.2 mg/ea>

MCP Server

compute(
    initial_value=154,
    initial_unit="lb",
    factors=[
        {"value": 1, "numerator": "kg", "denominator": "2.205 lb"},
        {"value": 15, "numerator": "mg", "denominator": "kg*day"},
        {"value": 1, "numerator": "day", "denominator": "3 ea"},
    ]
)

Step trace:

Step	Factor	Dimension	Result
0	154 lb	mass	154 lb
1	× (1 kg / 2.205 lb)	mass	69.84 kg
2	× (15 mg / kg·day)	mass/time	1047.6 mg/day
3	× (1 day / 3 ea)	mass/count	349.2 mg/ea

---

IV Drip Rate Calculations

Problem: Infuse 1000 mL over 8 hours using a drip set that delivers 15 drops/mL. What's the drip rate in drops/minute?

Python API

from ucon import units, Scale, Dimension
from ucon.core import Unit

mL = Scale.milli * units.liter

# Define custom unit for drops (not in standard library)
drop = Unit(name="drop", dimension=Dimension.count, aliases=("gtt", "drop"))

# Givens as callable units
volume = mL(1000)
drip_factor = (drop / mL)(15)  # 15 drops per mL
infusion_time = units.hour(8)

# Calculate: volume × drip_factor ÷ time
total_drops = volume * drip_factor
print(total_drops)  # <15000>

rate = total_drops / infusion_time
print(rate)  # <1875.0 gtt/h>

# Convert to drops/min
rate_per_min = rate.quantity / 60
print(f"{rate_per_min:.1f} drops/min")  # 31.2 drops/min

MCP Server

First, define the drop unit:

define_unit(name="drop", dimension="count", aliases=["gtt", "drop"])

Then calculate:

compute(
    initial_value=1000,
    initial_unit="mL",
    factors=[
        {"value": 15, "numerator": "drop", "denominator": "mL"},
        {"value": 1, "numerator": "1", "denominator": "8 hr"},
        {"value": 1, "numerator": "hr", "denominator": "60 min"},
    ]
)

Result: 31.25 drops/min (round to 31 gtt/min)

Custom Units in MCP

The drop unit isn't in ucon's standard library. Use define_unit to register it for the session before calling compute.

---

Concentration Conversions

Problem: A 1% solution means 1 g per 100 mL. Express this as mg/mL.

Python API

from ucon import units, Scale

mg = Scale.milli * units.gram
mL = Scale.milli * units.liter

# 1% = 1 g / 100 mL = 0.01 g/mL
concentration_g = units.gram(1) / mL(100)
print(concentration_g)  # <0.01 g/mL>

# Convert to mg/mL: 0.01 g = 10 mg
concentration_mg = mg(10) / mL(1)
print(concentration_mg)  # <10 mg/mL>

MCP Server

convert(value=1, from_unit="g/100mL", to_unit="mg/mL")
# → {"quantity": 10.0, "unit": "mg/mL", "dimension": "mass/volume"}

---

Dimensional Safety

ucon prevents nonsensical conversions in both interfaces.

Python API

from ucon import units, Scale
from ucon.graph import ConversionNotFound

mg = Scale.milli * units.gram
mL = Scale.milli * units.liter

dose = mg(500)
try:
    dose.to(mL)  # mg → mL makes no sense!
except ConversionNotFound:
    print("Cannot convert mass to volume without concentration")

MCP Server

convert(value=500, from_unit="mg", to_unit="mL")
# → {
#     "error": "Dimension mismatch: mass ≠ volume",
#     "error_type": "dimension_mismatch",
#     "likely_fix": "Use a mass unit, or provide concentration to bridge mass↔volume"
# }

Bridging Mass and Volume

You need concentration to convert between them:

# Python API
concentration = (mg / mL)(10)  # 10 mg/mL
dose_mg = mg(500)
volume = dose_mg / concentration
print(volume)  # <50.0 mL>

---

Full Example: Complex Dosing

Problem: A 68 kg patient needs vancomycin 15 mg/kg every 12 hours, diluted to a concentration of 5 mg/mL, infused over 60 minutes. Calculate:

1. Dose per administration (mg)
2. Volume of diluted solution (mL)
3. Infusion rate (mL/hr)

Python API

from ucon import units, Scale

mg = Scale.milli * units.gram
mL = Scale.milli * units.liter
kg = Scale.kilo * units.gram

# Givens as callable units
weight = kg(68)
dose_rate = (mg / kg)(15)  # 15 mg/kg
concentration = (mg / mL)(5)  # 5 mg/mL
infusion_time = units.hour(1)  # 60 minutes

# 1. Dose calculation: weight × dose_rate
dose = weight * dose_rate
print(f"Dose: {dose}")  # <1020 mg>

# 2. Volume calculation: dose ÷ concentration
volume = dose / concentration
print(f"Volume: {volume}")  # <204 mL>

# 3. Infusion rate: volume ÷ time
rate = volume / infusion_time
print(f"Rate: {rate}")  # <204 mL/hr>

MCP Server

All three calculations in one chain:

compute(
    initial_value=68,
    initial_unit="kg",
    factors=[
        {"value": 15, "numerator": "mg", "denominator": "kg"},
        {"value": 1, "numerator": "mL", "denominator": "5 mg"},
        {"value": 1, "numerator": "1", "denominator": "1 hr"},
    ]
)

Step trace:

Step	Factor	Result
0	68 kg	68 kg
1	× (15 mg / kg)	1020 mg
2	× (1 mL / 5 mg)	204 mL
3	× (1 / 1 hr)	204 mL/hr

---

Key Takeaways

1. Always track units through every calculation step
2. Both approaches validate dimensions — errors are caught, not silently computed
3. Mass ≠ Volume — you need concentration to bridge them
4. MCP step traces provide an audit trail for AI-assisted calculations
5. Python API gives you full control for integration into applications