rods/docs/engineering/units.md

Units and internal conventions

Owner: Rods Project Team
Status: Active
Last Updated: 2026-04-16

Principle

All values passed from solver-api to solver-c JSON are SI:

Quantity	SI unit
Length	m
Force	N
Pressure	Pa
Mass density	kg/m³
Time	s
Angle	rad (stored in JSON as rad; XML may be degrees)
SPM	1/min (dimensionally s⁻¹ scale; kept as pumping_speed scalar per stroke period (T = 60/\text{SPM}) s)

UnitsSelection (XML)

base-case.xml uses <UnitsSelection>2</UnitsSelection> (example). Parser maps:

Code	Assumption in parser
0 / missing	Field units match legacy oilfield mixed inch–ft–lbf where applicable (see below)
2	Imperial oilfield — lengths in ft, diameters in in, moduli in Mpsi (×10⁶ psi), forces in lbf, pressures in psi
Other	Treated like 2 with warning in parsed.warnings (heuristic)

Conversion factors (exact)

• 1 in = 0.0254 m
• 1 ft = 0.3048 m
• 1 lbf = 4.4482216152605 N
• 1 psi = 6894.757293168 Pa
• 1 Mpsi = 6.894757293168e9 Pa
• deg → rad: multiply by (\pi/180)

Fluid density helper

Mixture density from WaterCut, WaterSpecGravity, FluidLevelOilGravity uses simplified API formula for buoyancy; tagged heuristic in model.fluidDensityHeuristic.

JSON to C

SolverInputs receives only SI. GUI may show field units; API documentation states SI in solve payload.