pie-dimensional-analysis

Dimensional Analysis Skill

At a Glance

Dimensional analysis is the mathematical verification layer that ensures physical calculations are dimensionally consistent -- catching unit errors before they become calculation errors.

When to activate:

• Verify multi-step calculations for unit consistency
• Mix SI and Imperial units in the same calculation
• Scale experimental data to new conditions via dimensionless groups
• Identify governing parameters of a physical system
• Validate Calculator agent outputs before committing to CalculationRecord

Key capabilities:

• Unit tracking via exponent maps (PhysicalQuantity pattern)
• Compound unit algebra: multiply, divide, power, dimensional homogeneity
• Dimensional mismatch detection at every arithmetic step
• SI to Imperial conversion for all infrastructure engineering domains
• Buckingham pi theorem for deriving dimensionless groups
• Infrastructure dimensionless numbers: Reynolds, Nusselt, Prandtl, Grashof, Froude, Strouhal

Integration: Cross-cutting skill -- applies to outputs from fluid-systems, power-systems, and thermal-engineering. Acts as verification layer before Calculator agent commits to CalculationRecord.

NOTE: Dimensional analysis verifies mathematical self-consistency only. It does not replace engineering judgment or safety verification. Dimensionally correct equations can still be physically wrong if incorrect constants or assumptions are used.

Quick routing:

• Unit conversions only --> @references/unit-algebra.md for full tables
• Pi theorem derivation --> @references/buckingham-pi.md for worked examples
• Tolerance stack-up --> see Tolerance Stack-Up Analysis section below
• Spatial fit checking --> see Spatial Constraint Verification section below

Unit Tracking Algebra

The Seven SI Base Units

| Symbol | Quantity | Notes | |--------|----------|-------| | m | length | meter | | kg | mass | kilogram (only SI base unit with a prefix) | | s | time | second | | A | electric current | ampere | | K | temperature | kelvin (absolute; not degrees Celsius) | | mol | amount of substance | mole | | cd | luminous intensity | candela (rarely used in infrastructure) |

Compound Units as Exponent Maps

Every physical quantity carries its unit as a map of base unit exponents. This representation makes unit algebra mechanical -- multiply means add exponents, divide means subtract.

Examples:

• Velocity: 2.4 m/s --> { value: 2.4, units: { m: 1, s: -1 } }
• Pressure: 101325 Pa --> { value: 101325, units: { kg: 1, m: -1, s: -2 } }
• Power: 1000 W --> { value: 1000, units: { kg: 1, m: 2, s: -3 } }
• Thermal conductivity: 385 W/(m*K) --> { value: 385, units: { kg: 1, m: 1, s: -3, K: -1 } }

Common Infrastructure Units -- Exponent Map Reference

| Quantity | SI Unit | Symbol | Exponent Map | |----------|---------|--------|-------------| | Force | Newton | N | { kg:1, m:1, s:-2 } | | Pressure | Pascal | Pa | { kg:1, m:-1, s:-2 } | | Energy | Joule | J | { kg:1, m:2, s:-2 } | | Power | Watt | W | { kg:1, m:2, s:-3 } | | Dynamic viscosity | -- | Pa*s | { kg:1, m:-1, s:-1 } | | Heat transfer coeff | -- | W/(m^2*K) | { kg:1, s:-3, K:-1 } | | Thermal conductivity | -- | W/(m*K) | { kg:1, m:1, s:-3, K:-1 } |

The PhysicalQuantity Interface

The Calculator agent implements unit-safe arithmetic using this TypeScript pattern. The SKILL documents the knowledge; lib/units.ts provides the implementation.

interface PhysicalQuantity {
  value: number;
  units: { [baseUnit: string]: number }; // exponent map
}

function multiply(a: PhysicalQuantity, b: PhysicalQuantity): PhysicalQuantity {
  const result: PhysicalQuantity = { value: a.value * b.value, units: { ...a.units } };
  for (const [unit, exp] of Object.entries(b.units)) {
    result.units[unit] = (result.units[unit] || 0) + exp;
  }
  // Remove zero exponents
  for (const unit of Object.keys(result.units)) {
    if (result.units[unit] === 0) delete result.units[unit];
  }
  return result;
}

function divide(a: PhysicalQuantity, b: PhysicalQuantity): PhysicalQuantity {
  const negated = { value: 1 / b.value, units: Object.fromEntries(
    Object.entries(b.units).map(([k, v]) => [k, -v])
  )};
  return multiply(a, negated);
}

function assertSameUnits(a: PhysicalQuantity, b: PhysicalQuantity): void {
  const aKeys = Object.keys(a.units).sort().join(',');
  const bKeys = Object.keys(b.units).sort().join(',');
  if (aKeys !== bKeys || !Object.entries(a.units).every(([k, v]) => b.units[k] === v)) {
    throw new Error(`Unit mismatch: [${aKeys}] vs [${bKeys}] — cannot add/subtract`);
  }
}

Unit Algebra Rules

| Operation | Exponent Rule | Example | |-----------|---------------|---------| | Multiply | Exponents ADD | (m/s) * (m/s) = m^2/s^2 | | Divide | Exponents SUBTRACT | J / m^3 = Pa (energy density = pressure) | | Power n | Exponents MULTIPLY by n | (m^2)^0.5 = m | | Add/Subtract | Units must be IDENTICAL | m + m = m; m + s = ERROR | | Dimensionless | All exponents = 0 | units: {} (empty map) |

The dimensional homogeneity rule is absolute: you cannot add quantities with different units. If assertSameUnits() throws, the calculation has a structural error that must be fixed before proceeding.

Mixed Unit Systems

Infrastructure engineering inherently mixes SI and Imperial units. This is not optional -- it is driven by standards bodies, building codes, and equipment manufacturers.

Common mixed-unit scenarios:

• Pipe sizes: NPS in inches (ASME B36.10 standard)
• Flow rates: GPM (US practice) or L/s (SI practice)
• Pressure: PSI (US safety codes, ASME BPVC) or kPa (SI engineering)
• Temperature: degrees F (US weather/safety) or degrees C (SI engineering)
• Power: BTU/hr (US HVAC industry) or kW (SI)
• Conductors: AWG (US NEC) or mm^2 (EU/IEC)

Strategy: Convert Immediately, Work in SI, Convert Output

1. Receive mixed-unit inputs (e.g., pipe diameter in inches, flow in GPM)
2. Convert ALL inputs to SI at the boundary -- lib/units.ts handles this
3. Calculate entirely in SI using PhysicalQuantity arithmetic
4. Convert final outputs to user-preferred units for display

This eliminates mixed-unit errors in the calculation core. Conversion errors are isolated to the boundary layer where they are easy to audit.

Common Conversions -- Quick Reference

| From | To | Factor | |------|----|--------| | inches | meters | x 0.0254 | | feet | meters | x 0.3048 | | PSI | kPa | x 6.8948 | | GPM | L/s | x 0.06309 | | BTU/hr | W | x 0.29307 | | degrees F | degrees C | (F - 32) / 1.8 | | degrees C | K | + 273.15 | | ft/s | m/s | x 0.3048 | | lb/ft^3 | kg/m^3 | x 16.018 |

Full conversion table for all infrastructure engineering domains --> @references/unit-algebra.md

Buckingham Pi Theorem

The Theorem

For a physical equation relating n dimensional variables that involve k independent base dimensions, the equation can be rewritten using (n - k) independent dimensionless groups.

This means: if you have 6 variables and 3 base dimensions, you need only 3 dimensionless groups to describe the physics -- regardless of what unit system you use. The universe is dimensionally self-consistent.

Procedure (5 Steps)

1. List variables -- identify every physical quantity that could influence the outcome. Include the dependent variable.
2. Write dimensions -- express each variable in base units (m, kg, s, A, K).
3. Count k -- number of independent base dimensions appearing. Usually 2-4 for engineering problems.
4. Choose k repeating variables -- variables that together span all k dimensions. Avoid the dependent variable. Common choices: (rho, v, L) for fluid flows; (k, L, h) for heat transfer.
5. Form pi groups -- multiply each remaining variable with the repeating variables raised to unknown powers; solve exponents so that the result is dimensionless.

Worked Example: Pipe Flow Pressure Drop

Variables: delta_P (press