Conner Majic
725a72a773
Set up the C solver core, Node API orchestration, TS GUI workflow, and engineering documentation with cleaned repo hygiene for private Git hosting. Made-with: Cursor
85 lines
4.2 KiB
Markdown
85 lines
4.2 KiB
Markdown
# 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.
|