# 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.