wellcontrol

Deterministic well control & CWI (Completion and Well Intervention) physics engine, forward dynamic choke & BOP simulator, Model Context Protocol (MCP) agent server, and interactive kill planner covering vertical land wells, directional and horizontal wells, deepwater subsea wells, HPHT wells, and managed pressure / underbalanced operations.

Four parts that reference each other:

• src/wellcontrol/ — a tested, zero-dependency Python calculation library (dependencies = []) covering hydrostatics, directional surveys, rheology, kick analysis, 7 kill methods, CWI stripping/snubbing, subsea choke line friction, HPHT, and MPD.

• src/wellcontrol/sim/ — a real-time forward dynamic well control simulator and 7-screen rig instrument console (Driller's Console, Choke Panel, BOP Remote Panel, Standpipe & Choke/Kill Manifolds, Wellbore Schematic, Latched Kill Sheet, and Graded Debrief) served over FastAPI.

• src/wellcontrol/mcp_server.py — a built-in Model Context Protocol (MCP) Server exposing deterministic well control planning, CWI stripping/snubbing physics, and live simulator control to LLM agents so AI workflows never hallucinate safety-critical pressure math.

• app/ & content/ — a Streamlit kill planner and 13-chapter engineering textbook with worked examples verified against the solver.

flowchart LR
    subgraph Core["Zero-Dependency Physics Core (src/wellcontrol)"]
        Geo["Survey (MD/TVD) & Annular Geometry"]
        Round["Directional Rounding (KMW Up / MAASP Down)"]
        Methods["7 Kill Methods & Applicability Matrix"]
        CWI["CWI Stripping, Snubbing & Balance Point"]
    end

    subgraph Sim["Forward Dynamic Simulator (wellcontrol.sim)"]
        Engine["Transient Volume Balance & Boyle Gas Engine"]
        Flow["21-Node Rig FlowPath, BOP & Koomey Accumulator"]
        Panel["7-Screen Rig Instrument Console (FastAPI)"]
    end

    subgraph AI["Agentic AI Layer (wellcontrol.mcp_server)"]
        MCP["MCP Server (stdio / FastMCP / MCPServer)"]
        Tools["5 Deterministic Agent Tools"]
    end

    subgraph UI["Interactive Planner (app/ & content/)"]
        Streamlit["Streamlit Kill Planner & CSV/XLSX Importers"]
        Chapters["13 Engineering Chapters"]
    end

    Geo --> Methods
    Round --> Methods
    CWI --> Methods
    Core --> Engine
    Flow --> Engine
    Engine --> Panel
    Core --> Tools
    Engine --> Tools
    MCP --> Tools
    Core --> Streamlit
    Chapters --> Streamlit

Install

python -m venv .venv
source .venv/bin/activate       # Linux / macOS (.venv\Scripts\activate on Windows)
pip install -e ".[dev,app,sim,mcp]"
pytest

• [dev] alone gives the core library and test suite with no third-party dependencies.

• [app] adds matplotlib, streamlit, pandas, and openpyxl for the kill planner.

• [sim] adds fastapi, uvicorn, and httpx for the 7-screen real-time choke simulator.

• [mcp] adds mcp for the Model Context Protocol agent server.

Related MCP server: EPANET MCP Server

Real-Time Choke & BOP Simulator (wellcontrol.sim)

While the kill planner is an inverse solver ("what drill pipe pressure should the driller hold?"), wellcontrol.sim is a forward dynamic model ("the student set the choke to 35% and the pump to 30 SPM — what does the well do?"). Every failure mode—underbalance taking a secondary influx, over-pressuring the shoe into formation losses, pumping against a closed valve, running out of Koomey accumulator bottle pressure, or letting gas migrate in a shut-in well—emerges directly from the transient volume balance rather than scripted animations.

uvicorn wellcontrol.sim.api:app --reload --port 8000

Open http://127.0.0.1:8000 (or double-click Launch Simulator.bat on Windows) to operate the 10-screen self-contained industrial cyber-rig workstation:

1. Driller's Console (driller) — Standpipe pressure, SPM, pit gain, differential flow, hookload (buoyed string weight minus wellhead ejection force), bit depth, pipe moved, displacement, and stripping controls.

2. Remote Choke Panel (choke) — Authentic SWACO physical console face carrying four dials (Drill Pipe PSI, Casing PSI, Pump Strokes, Choke Position %) with valve travel lag, pump ramp rates, downhole pressure strip charts, and procedural audio.

3. EDR Trend Workstation (edr) — Electronic Drilling Recorder (Pason / Totco cyber-screen style) with customizable trend pens (SPP, SICP, SPM, Pit Gain, $\Delta\text{Flow}$, Hookload, Trip Tank, Choke %, BHP, Shoe Pressure), Split-Track vs. Multi-Pen Overlay modes, 1m–Full Run zoom, interactive crosshair scrub, and CSV export.

4. BOP Control Console (bop) — Immediate, race-free dual-mode blowout preventer interface:

   • Surface Koomey Type 80 Remote Control Console (API 16D): Heavy steel red cabinet, 4 chrome pressure gauges (Accumulator 3,000 psi, Manifold 1,500 psi, Annular Reg 1,000 psi, Air Supply 120 psi), reservoir sight glass, triplex electric & air backup charge pumps, 4-way rotary levers with status lamps, hazard safety guard on shear rams, choke/kill HCR wing modules, and a 12-bottle nitrogen accumulator bank.

   • Subsea Electro-Hydraulic MUX Monitoring System (API 16D / 53): Dual MUX control pods (Blue / Yellow), subsea telemetry readbacks (PT-1 mudline, PT-2 choke conduit), stack elevation with flex joint, LMRP collet connector, annulars, shear/pipe rams, wellhead connector, mudline seabed (5,280 ft), and guarded EDS disconnect.

5. Standpipe & Choke/Kill Manifolds (manifolds) — Rigorous API Spec 16C piping mimics with digital Tap 1 / Tap 2 pressure gauges, triplex mud pumps MP1 & MP2, mud-gas separator (poor boy degasser) lines, emergency bypass, and scrollable all-valves lineup panel.

6. Mud Pits & Calibrated Trip Tank (pits) — Full API Spec 13C / IADC PVT workstation featuring live active mud volume (bbl), pit gain/loss with auto-alarming, differential flow (bpm), 50-bbl calibrated trip tank with 0.5-bbl graduations and float indicator, venturi mixing hopper for mud weight adjustment, and an 8-column Stand-by-Stand tripping sheet with auto-logging and swabbing diagnostics.

7. Wellbore Schematic (well) — Live fluid column cross-section with Taylor gas bubble dynamics, casing shoe, cement sheath, drill bit nozzles, and formation stratigraphy.

8. Kill Sheet (sheet) — Built from the student's own latched shut-in readings (SIDPP, SICP, pit gain) with live step-down schedule.

9. Post-Run Debrief (debrief) — Automated grading (excellent, pass, marginal, fail) against scenario limits, AI coaching deductions, and 1-click export of certified kill plots with metadata title block.

10. Guide & Operations Coach (guide) — Live step-by-step well control procedural checklist, diagnosis engine, and operational rules of thumb.

11. Modern Cyber-Rig UI Architecture — Dark titanium/graphite console palette (#0b0f17 ground, #111827 cards, #06090e digital windows, #1e293b borders) with custom dark scrollbars, decoupling the physical SWACO orange choke console face from modern cyber screens.

12. AI Intelligent Coach & Scoring — Automated IADC/IWCF scoring (0–100, letter grade, category breakdowns, point deductions with physical justifications, strengths, and chronological timeline).

13. Instructor Master Station (/teacher) — Live multi-student grid dashboard, remote master freeze / whiteboard mode, dynamic fault injection (pump failure, choke plug, accumulator leak, mud weight drop), cohort gradebook export (JSON & RFC 4180 CSV), and flight-recorder telemetry replay scrubbing.

14. Procedural Rig Audio Engine — 100% offline Web Audio synthesis of triplex mud pump thumps, choke fluid/gas shearing hiss, BOP mechanical actuation clunks, and alarm sirens.

15. Crew Resource Management (CRM) Mode (/crew) — Multi-student collaborative team simulator supporting IADC WellSharp & IWCF Level 4 crew training. Distributes operational authority across dedicated rig-floor stations (Driller, Choke Operator, Toolpusher, Mud Engineer, Observer) with real-time WebSocket synchronization, role permission gating, tactical VHF intercom radio callouts, and live multi-user telemetry.

16. Multi-Monitor Detachable Cockpit Suite — One-click window detachment for physical dual/triple-monitor simulator setups. Pop out individual workstations (Remote Choke, Driller's Doghouse, Manifolds P&ID, BOP Stack, Wellbore Schematic, EDR Trends) or launch an auto-tiled 3-screen rig suite with sub-millisecond cross-window state synchronization via BroadcastChannel.

17. Visual Scenario & Custom Well Program Builder — Graphical curriculum designer in /teacher allowing instructors to define custom casing depths, shoe fracture gradients (LOT), mud programs, initial shut-in pressures (SIDPP/SICP), and scripted in-flight faults (choke plug/washout, pump breakdown, accumulator leak) saved to disk and instantly deployed to trainees.

18. Oil-Based Mud (OBM) Gas Solubility & Flash Breakout Engine — Downhole PVT methane dissolution model in hydrocarbon base oil. Conceals influx downhole with only ~12% liquid swelling volume and near-zero pit gain, followed by rapid, violent methane breakout above the bubble point (1,500 psia) as gas flashes out of solution near surface.

19. Certified Kill Plot & Audit Title Block (plot_kill, plot_session_kill, save_kill_plot) — Standardized oilfield engineering certification title block stamped onto every diagnostic kill plot (both theoretical method plans and live simulator runs). Displays Student Name, Instructor / Assessor Name, Complication / Incident, Well Name, and Date & Time, alongside verification standards and grading scores. Supports 1-click high-resolution PNG & vector SVG export from both the student console (/ Debrief) and instructor master station (/teacher).

Model Context Protocol (MCP) Server for AI Agents

LLMs are notoriously unreliable at oilfield unit conversions, minimum-curvature TVD integration, and directional rounding. wellcontrol.mcp_server exposes 5 deterministic tools over stdio so AI agents (Claude Desktop, Cursor, OpenAI Agents SDK, LangGraph) can plan well kills, evaluate CWI stripping/snubbing operations, and fly the simulator:

python -m wellcontrol.mcp_server

The kill planner

streamlit run app/streamlit_app.py

Or double-click Launch Kill Planner.bat, which builds the environment on first run and binds to localhost only.

Two pages:

• Kill Planner — select one of four well configurations and one of seven kill methods. The app builds the geometry, plans the kill, and shows the step-by-step procedure with diagnostic plots: circulating pressures, pressure at the casing shoe against the fracture limit, influx volume, influx position, and bit depth while stripping. Each plan links through to the chapter explaining its method.

• Learn — the content/ chapters rendered in the app, with a contents list and prev/next navigation.

Importing real geometry

The planner accepts a directional survey and a pipe tally as CSV or Excel, replacing the idealised geometry. TVD then comes from the actual trajectory (minimum curvature) and string volume from the actual components — which is what kill mud weight and strokes to bit are built on.

from wellcontrol.importers import import_survey, import_tally

survey = import_survey("samples/survey_horizontal.csv").survey
tally = import_tally("samples/pipe_tally.csv").components

Working examples of both formats, and the accepted column headings, are in samples/.

Combinations that cannot work say so. Volumetric and Lube-and-Bleed both depend on gas migrating upward, and gas in a horizontal lateral does not migrate, so those are reported as blocked rather than producing numbers for a procedure that would stall on the rig.

from wellcontrol import examples, plan_kill
from wellcontrol.wellconfig import WellConfiguration, BOPLocation, Trajectory

well = examples.well_state(
    WellConfiguration(BOPLocation.SUBSEA, Trajectory.HORIZONTAL))

plan = plan_kill(well, "wait_and_weight")
print(plan.format_summary())
print(plan.peak_shoe_pressure_psi, "psi at the shoe")

Five minutes in

from wellcontrol import examples

sheet = examples.vertical_land_well_kill_sheet()

for key, value in sheet.summary().items():
    print(f"{key:.<40} {value}")

print()
print(sheet.format_schedule(sheet.schedule_by_depth(steps=10)))

Abridged output:

Original mud weight (ppg)............... 9.6
Kill mud weight, calculated (ppg)....... 10.369
Kill mud weight, as mixed (ppg)......... 10.4
Formation pressure (psi)................ 5392
ICP (psi)............................... 1000
FCP (psi)............................... 650
Pressure per step, 10 steps (psi)....... 35
Strokes to bit.......................... 1466
Total strokes........................... 5483

Rounding in well control is directional — every rule goes the way that adds margin. Kill mud weight rounds up, limits like MAASP round down, strokes round up. See the rounding rules.

What is covered

Kill methods

Each is planned against any of four configurations — Surface/Subsea BOP × Vertical/Horizontal. See Choosing a kill method for the applicability matrix and why two cells are empty.

Content

Read in order, or jump to the well type you are working on.

1. Fundamentals

2. Hydrostatic pressure

3. Wellbore volumes and strokes

4. Kick detection and shut-in

5. The kill sheet

6. Circulation methods

7. Kick tolerance and MAASP

8. Directional and horizontal wells

9. Subsea wells

10. HPHT wells

11. MPD and underbalanced drilling

12. Choosing a kill method

13. Stripping and snubbing

Reference wells

Three wells run through the tests and the content, chosen because they fail in different ways:

from wellcontrol import examples

annulus, survey = examples.horizontal_well()
sheet = examples.horizontal_well_kill_sheet()

A note on the constant 0.052

Every gradient in this library uses the field-standard rounded constant:

gradient (psi/ft) = 0.052 × mud weight (ppg)

The unrounded value is 1/19.25 = 0.051948. The gradient functions accept exact=True if you want it, but 0.052 is what appears on every kill sheet and every exam, and the 0.1% difference is far smaller than the uncertainty in the mud weight itself.

Scope and limits

• Friction correlations are approximations. Where a measured slow circulating rate pressure exists, use it in preference to anything computed here.

• Gas is treated as ideal and isothermal unless you supply temperatures and z-factors. This slightly over-estimates expansion, which errs toward caution for kick tolerance.

• HPHT density uses a linear PVT model with representative coefficients. Real HPHT work needs lab-measured PVT data for the actual mud.

These are engineering aids, not a substitute for certification, a company well control manual, or the judgement of a competent person on the rig. Verify against your own procedures before using any of it operationally.

License

MIT