rods/docs/engineering/field-traceability.md

Field Traceability Matrix

Last Updated: 2026-04-17

Scope

This matrix tracks how data/cases/base-case.xml fields flow through the solver:

1. XML parse (solver-api/src/xmlParser.js)
2. SI conversion (normalizeToSi)
3. C payload (solver-api/src/solverClient.js)
4. Equation/physics use (solver-c/src/*.c)

Coverage summary (base-case)

• Total XML fields: 165
• Fields present in MVP schema and present in base-case: 41
• Unsupported/preserved fields: 124

A) Fully used in solver equations

XML field	Parsed + SI	Payload key(s)	Equation use
PumpingSpeed	yes	pumping_speed	time step / period in FDM/FEA
PumpDepth	yes	pump_depth	rod length, hydrostatic terms
TubingAnchorLocation	yes	tubing_anchor_location	rod length
RodFrictionCoefficient	yes	rod_friction_coefficient	Coulomb friction scaling
StuffingBoxFriction	yes	stuffing_box_friction	polished-load boundary friction
PumpFriction	yes	pump_friction	downhole boundary friction
MeasuredDepthArray	yes	survey_md_m	trajectory/node mapping
InclinationFromVerticalArray	yes	survey_inc_rad	trajectory + gravity projection
AzimuthFromNorthArray	yes	survey_azi_rad	trajectory curvature
TaperDiameterArray	yes	area_m2	axial stiffness/mass terms
TaperLengthArray	yes	rod-node assembly	rod section distribution
TaperModulusArray	yes	modulus_pa	stiffness terms
RodTypeArray	yes	density/modulus defaults	mass/stiffness terms
UpStrokeDampingFactor	yes	upstroke_damping	FEA damping calibration
DownStrokeDampingFactor	yes	downstroke_damping	damping (path-level)
NonDimensionalFluidDamping	yes	non_dim_damping	FEA damping factor
MoldedGuideFrictionRatio	yes	molded_guide_mu_scale	friction scaling
WheeledGuideFrictionRatio	yes	wheeled_guide_mu_scale	friction scaling
OtherGuideFrictionRatio	yes	other_guide_mu_scale	friction scaling
PumpDiameter	yes	pump_diameter_m	chamber pressure / valve logic
PumpIntakePressure	yes	pump_intake_pressure_pa	hydro/chamber pressure
PumpFillageOption	yes	pump_fillage_option	gas-interference logic
PercentPumpFillage	yes	percent_pump_fillage	gas-fraction logic
WaterCut + WaterSpecGravity + FluidLevelOilGravity	yes	fluid_density_kg_m3	buoyancy/hydrostatic terms
TaperWeightArray	yes	weight_n_per_m	node buoyed-weight in side-load
TaperMTSArray	yes	mts_n	friction scaling term
RodGuideWeightArray	yes	guide_weight_n_per_m	side-load normal-force term
SinkerBarDiameter + SinkerBarLength	yes	sinker_bar_*	added sinker side-load contribution

B) Parsed/payloaded but not yet active in governing equations

XML field	Current state	Planned use
TubingSize	parsed + converted to tubing_id_m + payloaded	annular buoyancy/contact refinements
TubingGradient	parsed + converted to tubingGradientPaM; not payloaded to C math	hydraulic pressure model
PercentageUpstrokeTime	payloaded (percent_upstroke_time)	non-harmonic kinematics timing
PercentageDownstrokeTime	payloaded (percent_downstroke_time)	non-harmonic kinematics timing
PumpingUnitID	parsed only	pumping-unit geometry/kinematics tables
PumpingSpeedOption	parsed only	drive/kinematics modes
RodGuideTypeArray	parsed only	type-specific contact/friction law

C) Unsupported but preserved in API

All non-MVP fields from base-case remain in rawFields and are listed in unsupportedFields; they are not currently used in C equations.

Representative examples:

• ActualCounterbalance
• BulkModulus
• CasingHeadPressure
• PumpEfficiency
• IPRInputMode
• VogalPointList
• SeparatorPressure
• PowerLineFrequency

D) Contract notes

• Heavy output blocks (profiles, diagnostics, fourierBaseline) are emitted by C.
• Fourier baseline is computed when options.enableFourierBaseline=true.
• Default deterministic golden hash updated after physics/field-wiring changes.