rods/docs/engineering/case-schema.md

Case schema and import contract

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

Canonical input

• Root: INPRoot/Case
• Example: data/cases/base-case.xml

Parsed fields used by solver (SI after xmlParser)

Core (required)

• PumpingSpeed — SPM
• PumpDepth — MD to pump (case units → m)
• MeasuredDepthArray, InclinationFromVerticalArray — trajectory (: separated)
• AzimuthFromNorthArray — optional for vertical; required for full 3D curvature in API validation

Friction / contact

• RodFrictionCoefficient — Coulomb (\mu) baseline
• StuffingBoxFriction, PumpFriction — case force units → N
• MoldedGuideFrictionRatio, WheeledGuideFrictionRatio, OtherGuideFrictionRatio — scale effective (\mu) along string (heuristic blend)

Rod string / materials

• TaperDiameterArray, TaperLengthArray, TaperModulusArray, TaperWeightArray, TaperMTSArray
• RodTypeArray — maps to steel vs fiberglass density/modulus defaults when modulus not set
• TubingAnchorLocation
• SinkerBarDiameter, SinkerBarLength
• RodGuideTypeArray, RodGuideWeightArray — metadata / future contact

Damping

• UpStrokeDampingFactor, DownStrokeDampingFactor
• NonDimensionalFluidDamping — Gibbs-style dimensionless damping input

Pump / fluid (valve + buoyancy helpers)

• PumpDiameter, PumpIntakePressure, PumpFillageOption, PercentPumpFillage
• WaterCut, WaterSpecGravity, FluidLevelOilGravity, TubingGradient, TubingSize
• PercentageUpstrokeTime, PercentageDownstrokeTime
• PumpingUnitID, PumpingSpeedOption — metadata for future kinematics

Units

• UnitsSelection — drives internal conversion (see units.md)

Unknown / unsupported field policy

• Parse immediate Case children into rawFields.
• Fields outside the MVP subset used for solver remain in unsupportedFields but are preserved in API responses.
• Do not silently drop imported tags.

Validation rules

• Required for parse: PumpingSpeed, PumpDepth, MeasuredDepthArray, InclinationFromVerticalArray.
• Trajectory arrays must have equal lengths after parse.
• Numeric parse failures throw explicit errors.