Initial commit: establish deterministic rod-string solver stack.
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
This commit is contained in:
69
AGENTS.md
Normal file
69
AGENTS.md
Normal file
@@ -0,0 +1,69 @@
|
||||
# Agent rulebook — Rods Cursor solver
|
||||
|
||||
This file is the **canonical** instruction set for AI agents working in this repository. Read it before changing code or docs.
|
||||
|
||||
## Authoritative docs (read order)
|
||||
|
||||
1. **[Agents/MATH_SPEC.md](Agents/MATH_SPEC.md)** — Equations, discretization, BCs, paper citations (`references/papers/README.md`). **Do not invent math** not grounded there or in a cited calibration test.
|
||||
2. **[Agents/COMPUTE_PLAN.md](Agents/COMPUTE_PLAN.md)** — Living handoff: repo map, current gaps vs `MATH_SPEC.md`, deferred work, jump table.
|
||||
3. **[README.md](README.md)** — Human/agent quickstart, API examples, validation commands.
|
||||
|
||||
## Product intent
|
||||
|
||||
Build a **transparent, deterministic** rod-string / dynamometer solver stack: **C** is the authoritative numerics engine (predictive + diagnostic, FDM + FEA); **Node (`solver-api`)** is XML/IO, orchestration, card QA, and API versioning; **TypeScript (`gui-ts`)** is workflow and visualization (not the primary solver).
|
||||
|
||||
Outcomes:
|
||||
|
||||
- Physically explainable outputs, not black-box curves.
|
||||
- **Dynamometer cards** (polished + downhole) as the central engineering surface.
|
||||
- Preserve **inspectability** of imported XML (`rawFields`, `unsupportedFields`, `verbose`).
|
||||
- Multi-model workflows: run **FDM** and **FEA**, compare, surface discrepancies and assumptions.
|
||||
|
||||
## Architecture (non-negotiable)
|
||||
|
||||
| Layer | Responsibility |
|
||||
|-------------|----------------|
|
||||
| `solver-c/` | All heavy numerics: damped wave FDM, bar FEM, trajectory preprocess, diagnostic transfer, gravity/buoyancy, deviated-well friction proxies, iterative diagnostic FEA when enabled. |
|
||||
| `solver-api/` | HTTP, `parseCaseXml`, SI normalization, JSON → C stdin, surface-card QA, response shaping (`schemaVersion`, `comparison`, `verbose`, `pumpMovement`). |
|
||||
| `gui-ts/` | UI: import, plots, 3D survey when implemented, warnings. **No** primary PDE solve in TS except temporary shims during migration (avoid new TS numerics). |
|
||||
|
||||
Same C binaries power Docker, local `make test`, and CI.
|
||||
|
||||
## Guardrails
|
||||
|
||||
- **Determinism:** identical inputs → identical outputs (regression tests and golden hashes depend on this).
|
||||
- **API fields:** do not remove `verbose`, `pumpMovement`, or `comparison` without bumping `schemaVersion` and documenting migration.
|
||||
- **No undocumented “magic” multipliers.** If a simplification is not in `MATH_SPEC.md`, tag it `heuristic` in code comments and add a ticket in `COMPUTE_PLAN.md` or a calibration test in `docs/engineering/validation.md`.
|
||||
- **XML:** never fabricate field names or values not read from a real case file. Unknown fields stay in `rawFields` / `unsupportedFields`.
|
||||
- **Units:** internal solve uses **SI** (`docs/engineering/units.md`). Convert at the API/parser boundary.
|
||||
- **Papers:** grounding lives in `references/papers/README.md` (Romero & Almeida; Everitt & Jennings; SPE-173970 Araujo et al.; Eisner et al.).
|
||||
|
||||
## GUI (product)
|
||||
|
||||
The GUI is first-class for end users: continuous visibility of survey and cards, 3D trajectory when implemented, side-by-side solver comparison. Agent work may still touch **compute-only** paths without GUI in a given PR; do not add new numerics in the GUI.
|
||||
|
||||
## When you change the solver
|
||||
|
||||
1. Update `MATH_SPEC.md` if equations or BCs change.
|
||||
2. Update `COMPUTE_PLAN.md` gap table / status.
|
||||
3. Run `make test` and golden regression (`solver-api` tests include golden hash where configured).
|
||||
4. If C CLI or JSON contract changes, update `README.md`, `docker-compose.yml` gcc lines, and root `Dockerfile` compile commands.
|
||||
|
||||
## Repository map (compute)
|
||||
|
||||
| Path | Role |
|
||||
|------|------|
|
||||
| `solver-c/src/solver.c` | FDM predictive + shared numerics |
|
||||
| `solver-c/src/solver_fea.c` | FEA predictive + diagnostic iteration (when applicable) |
|
||||
| `solver-c/src/solver_diagnostic.c` | Diagnostic FDM (surface card BC) |
|
||||
| `solver-c/src/trajectory.c` | Survey → curvature / inclination on rod grid (SPE-173970 style) |
|
||||
| `solver-c/src/json_stdin.c` | Minimal JSON stdin parser for C drivers |
|
||||
| `solver-api/src/solverClient.js` | Build SI JSON, `execFile` C with stdin |
|
||||
| `solver-api/src/xmlParser.js` | Parse case + SI conversion |
|
||||
| `solver-api/src/app.js` | Routes, comparison payload, `schemaVersion` |
|
||||
| `data/cases/base-case.xml` | Canonical regression case |
|
||||
| `data/golden/` | Golden response fingerprints |
|
||||
|
||||
---
|
||||
|
||||
*Merged from legacy `Agents/Instructions.md`. Product vision details are maintained in `README.md`.*
|
||||
Reference in New Issue
Block a user