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
71 lines
3.8 KiB
Markdown
71 lines
3.8 KiB
Markdown
# Architecture and requirement traceability
|
|
|
|
Owner: Rods Project Team
|
|
Status: Active
|
|
Last Updated: 2026-04-16
|
|
Version: 0.2.0
|
|
|
|
## Module boundaries
|
|
|
|
- **`solver-c`:** Authoritative numerics — FDM, FEA, diagnostic FDM, trajectory preprocess, distributed side-load/friction coupling, valve/gas dynamic diagnostics, optional Fourier analytical baseline, gravity/buoyancy, variable \(E(x), A(x), \rho(x)\), JSON **stdin** contract (`schemaVersion: 2`). No HTTP/XML.
|
|
- **`solver-api`:** Local HTTP service — parse XML, convert to **SI**, surface-card QA, spawn C binaries with JSON pipe, attach `verbose`, `comparison`, `pumpMovement`, `schemaVersion`.
|
|
- **`gui-ts`:** Workflow and visualization (tabbed case editor, XML round-trip, dynacards, engineering checks, 3D wellbore preview); not the primary PDE solver.
|
|
- **`data/cases`:** Canonical inputs and regression cases.
|
|
- **`data/golden`:** Fingerprints for deterministic API regression.
|
|
- **`references/papers/README.md`:** Citation index for external literature used by `Agents/MATH_SPEC.md`.
|
|
|
|
## C driver contract
|
|
|
|
Executables read **one JSON object from stdin** (UTF-8). Required top-level keys are produced by `solver-api/src/solverClient.js` — see that file for the exact shape (`workflow`, `model`, optional `surfaceCard`, optional `options`).
|
|
|
|
`options` supports:
|
|
- `enableProfiles` — includes trajectory + side-load + friction profile payloads.
|
|
- `enableDiagnosticsDetail` — includes valve-state and chamber/gas time-series.
|
|
- `enableFourierBaseline` — computes analytical Fourier baseline in C.
|
|
- `fourierHarmonics` — harmonic count for baseline reconstruction.
|
|
|
|
Legacy argv-based invocation has been **removed** to avoid drift between CLI and API.
|
|
|
|
## MVP requirement traceability
|
|
|
|
| Requirement | Module | Notes |
|
|
|-------------|--------|--------|
|
|
| Real C solver path | `solver-c`, `solver-api` | JSON pipe; no mock-only solve |
|
|
| XML inspectability | `solver-api`, `gui-ts` | `rawFields`, `unsupportedFields` |
|
|
| Output cards primary | `solver-c`, `gui-ts` | Polished + downhole series |
|
|
| Determinism | `solver-c`, `solver-api` | Golden hash; no randomness |
|
|
| Warnings / numerics | `solver-c`, `solver-api` | `warnings`, `verbose.numerics`, CFL |
|
|
| 3D survey visibility | `gui-ts` | Results tab includes projected 3D wellbore with DLS/side-load overlay modes + rod/pump overlays + interactive camera controls |
|
|
|
|
## System flow
|
|
|
|
1. GUI or client sends XML (+ options) to API.
|
|
2. API parses to canonical **SI** model + preserves unknown fields.
|
|
3. Optional: `POST /solve/validate-card` runs QA only.
|
|
4. API builds JSON and runs `solver_main` / `solver_fea_main` with stdin.
|
|
5. C returns JSON stdout; API merges `parsed`, `comparison`, `runMetadata`.
|
|
6. GUI renders cards, survey, inspection panels.
|
|
|
|
## Execution guidelines for upcoming hardening
|
|
|
|
- Keep defaults stable; grow contract additively behind options.
|
|
- Treat C as numerical source-of-truth; API orchestrates and validates.
|
|
- Require test evidence for every new equation term:
|
|
- unit-level numeric sanity,
|
|
- integration-level behavior,
|
|
- deterministic regression impact.
|
|
- Pair every new feature with:
|
|
- one "happy path" case,
|
|
- one edge/stress case,
|
|
- one regression gate entry.
|
|
|
|
## GUI guardrails and thresholds
|
|
|
|
- Pump-depth consistency gate: solver run is blocked when `abs(PumpDepth - totalRodLength) > 15 m`.
|
|
- DLS bad-section threshold: `15 deg/100` used both for warning logic and 3D contour highlighting.
|
|
- Thresholds are intentionally fixed (not user-configurable) to keep deterministic behavior.
|
|
- Diagnostic GUI path is now wired:
|
|
- measured card input + QA call in Kinematics tab,
|
|
- `workflow=diagnostic` run from Solver tab with `surfaceCard` payload.
|
|
- Results now include trajectory segment analytics and artifact export actions (3D SVG/PNG, summary JSON).
|