Wellbore Genius — User Manual

Wellbore Genius uses the standard industry hierarchy. Everything you do happens inside this tree:

• Project — top-level container for a field, pad, or study (e.g. 'Bakken Tutorial').
• Workspace (a.k.a. Sandbox) — a working set of related simulations that share a base template.
• Simulation — one numerical model. You edit, validate, run, and view results at this level.

Where to make changes#

All model edits happen in the Builder. Open it from a simulation row → Edit in Builder. Inside, the panels follow this fixed industry-standard order:

• Welcome · Startup · Static model · Curve sets · Wells & perforations · Meshing · Fluid model · Fracture options · Proppants · Water solutes · Well controls · Output.

Builder header buttons (left → right)#

• Next Panel — advance to the next ordered panel.
• Validate — run all rule checks (units, ranges, missing fields).
• Discard current changes — revert to the last save.
• Save Changes — commit edits. Greyed out when there are no pending edits.
• Show/Hide tutorial steps — overlays numbered steps on the current panel.
• Comments file — attach a free-text note to the simulation.
• Save as template — promote the current sim to a reusable template.
• Export — JSON / CSV / Calibration report (PDF + CSV).
• Exit Builder — return to the simulations list.

What's new (July 2026)#

• FDI bidirectional loop — parent-depletion Δσ_h is fed back into child-frac growth each timestep, with a SWPM residual → pump-rate advisory (`/fdi-loop`).
• Live+ diagnostics pack — step-down inverter, entry-friction P10/P50/P90, DFIT pre-closure classifier, and a wellbore fluid-front animator on `/live-pumping`.
• Driller's Copilot — voice-driven hold / rate-cut / advance-stage advisories for the frac van (`/driller-copilot`).
• EDFM + MINC hybrid solver — embedded DFN + multiple-interacting-continua transfer in one linear-system solve (`/edfm-minc`).
• Regulatory pack v2 — Subpart W CH₄ XML, OGMP 2.0 Level 4/5, CO ECMC CIDER, NM_OCD TLP, and CA LCFS exports on `/regulatory-exports`.
• PVT consortium presets — one-click Wolfcamp / Bakken / Eagle Ford / Marcellus / Montney / Vaca Muerta EoS + tuning (`/pvt-consortium`).
• DAS → cluster ε → fracture-geometry inversion — per-cluster half-length from live DAS intake fractions, mounted under the DAS section of `/live-pumping`.
• Compositional 3-phase black-oil wiring with energized-CO₂ gas FVF bridge in the Fluid model panel.

This walkthrough builds the Bakken reference case. Every panel below corresponds to a tab in the Bakken-tutorial Excel workbook. Use 'Paste from Excel tab' on each panel if you have the workbook open.

Step-by-step#

1. Create a Project, then a Workspace inside it. The first time you see the Workspace landing page, you'll see an 'a.k.a. Sandbox' alias chip — click it once to dismiss.
2. From the Workspace, click + New simulation → choose the Bakken template. This pre-fills PVT, conductivity, mesh, and SHmax (42°).
3. Click Edit in Builder. You'll land on the Welcome panel. Click Next Panel to step through all 12.
4. Startup — set simulation name, time controls, and output cadence. Tutorial steps overlay (top-right toggle) shows the recommended values.
5. Static model — geomechanics layers, stress, pore pressure. Bakken preset already has SHmax = 42°.
6. Curve sets — load relative permeability and capillary curves. Use Paste from Excel tab if you have the workbook.
7. Wells & perforations — Wellhead x-position [ft], Wellhead y-position [ft], TVD [ft], lateral length, cluster spacing.
8. Meshing — domain size and grid resolution. Smaller cells = more accurate but slower. The Bakken preset is balanced for tutorial speed.
9. Fluid model — water/oil/gas PVT. Bakken preset is pre-loaded.
10. Fracture options — set fracture toughness K_IC, leak-off Carter coefficient C_L, and fracture height growth rules. See Section 6 for the equations.
11. Proppants — proppant type, mesh size, conductivity multipliers. Bakken preset uses 100-mesh + 40/70.
12. Water solutes — chemistry tracer setup. Optional unless you're modelling a specialty material (Section 4).
13. Well controls — pump schedule (rate vs. time, proppant concentration ramp).
14. Output — what to save. Defaults are fine for tutorials.
15. Click Validate. Fix any red-flagged issues (missing units, out-of-range values).
16. Click Save Changes, then Exit Builder.
17. From the simulation row, click Run (local) or Run on Server. Status chips show queued → running → completed.
18. When the chip turns green, click the simulation → Results to view pressure, rate, fracture geometry, and proppant placement plots.

1. Open the simulation in Builder. Click Calibration in the sidebar (or press G then C).
2. Click Import DFIT and choose your pressure-vs-time CSV. Columns must include time and surface pressure (units in headers, e.g. 'p_surf [psi]').
3. The wizard auto-converts to bottomhole pressure using the wellbore hydrostatic snapshot (TVD + fluid density at reservoir temperature).
4. Pick the closure event on the G-function plot. The wizard fits T₀ (tensile strength) and K_IC (mode-I fracture toughness) using least-squares against the closure tail.
5. Review the fitted values in the right rail. The Pressure advisor wizard will use these as defaults next time.
6. Builder header → Export → 'Calibration report (PDF + CSV)' to save the inputs, assumptions, fitted values, and hydrostatic snapshot for handoff.

Pressure advisor (4 steps)#

1. Builder header → Pressure advisor. Auto-prefills TVD from `inputs.mesh` midpoint, reservoir temperature from `inputs.fluid`, and last calibration point.
2. Step 1 — Inputs. Review TVD, reservoir T, mud weight, frac gradient, K_IC, T₀. The Validation & warnings panel flags any value outside the realism band.
3. Step 2 — Mud weight. Convert between ppg and psi/ft. The graph shows hydrostatic vs. depth.
4. Step 3 — Surface budget. The advisor sums hydrostatic + friction + breakdown - pore to get required surface pressure, then compares against your pump rating.
5. Step 4 — Breakdown. Shows P_breakdown = SH_min + T₀ - P_pore at the perf depth. If the surface budget exceeds your pump rating, the advisor recommends the smallest mud-weight bump that closes the gap.
6. Click Apply to write the recommended values back to Wells & perforations + Well controls. Or Reset to default values to discard.

Expert setup — JSON scenario IO#

Use Expert setup when you want to script many scenarios or hand off the exact inputs to a colleague. Each wizard's inputs round-trip through a versioned `.scenario.json` file.

1. Open any wizard. Click Export scenario → choose .scenario.json. The file includes a kind (pressureAdvisor / expertJobSetup / stepDownTest) and a strict, Zod-validated inputs block.
2. To author by hand, click Sample templates and download the version you need (v1, v2, …). The current SCENARIO_JSON_VERSION is auto-stamped.
3. Use 'inputs-only' template if you're injecting into an existing envelope.
4. Click Import scenario, paste or upload the file. Older versions auto-upgrade. Lossy CSV imports show a per-field diff before applying.

Each example below is small enough to retype in 2-3 minutes. Inputs are typical field values from public Bakken / Permian / Marcellus datasets. Equations match Section 6. The 'Try it yourself' callout points to the exact route to reproduce the result.

Example 1 — Bakken DFIT: fit T₀ and K_IC, then size surface pressure#

A Middle-Bakken DFIT (TVD 10,500 ft, BHST 240 °F) was pumped at 2 bpm for 4 min, then shut in. Closure picked at 7,820 psi BHP from the G-function plot.

The Calibration wizard then least-squares-fits K_IC against the closure tail (Carter II falloff). For this trace, the fit returns K_IC ≈ 1.2 MPa·√m (≈ 1,090 psi·√in).

Example 2 — Permian Wolfcamp surface-pressure budget#

Permian Wolfcamp horizontal at TVD 9,800 ft, lateral 9,500 ft, 4½-in casing. Plan: 80 bpm slickwater, 1.5 ppa peak proppant. Question: does the existing 10,000-psi surface pressure rating cover the breakdown?

Example 3 — Parent-child screening on a 660-ft Bakken infill#

Two parent wells produced for 3 years (drawdown ≈ 1,800 psi each, drainage radius ≈ 450 ft). New child well drilled 660 ft to the south. Question: is asymmetric growth toward the depleted side likely, and how much proppant lands at the parents?

Example 4 — Catching a screen-out 90 s before it happens#

Live pumping a 100-mesh + 40/70 stage at 80 bpm. The actual BHP is rising 35 psi/min faster than the planned curve. Is this a screen-out brewing, or just normal proppant ramp friction?

Example 5 — SHmax azimuth from microseismic focal mechanisms#

A treatment in the Eagle Ford produced 14 located events with focal-mechanism solutions during the first 6 stages. Goal: recover SHmax azimuth and stress ratio R = (S2 − S3) / (S1 − S3) so the parent–child engine can rotate σh per stage instead of assuming the regional value.

Example 6 — Embedded DFN: matrix–fracture transfer in a Wolfcamp shale#

A Wolfcamp dual-porosity cell with k_matrix = 0.0001 mD (1e-19 m²) and a single embedded fracture (k_f = 50,000 mD, half-aperture 1.5 mm, contact area 100 m²). Question: what is the matrix→fracture connectivity index (CI), and how fast does the matrix bleed off into the fracture during a 1-hour shut-in?

Example 7 — Proppant bank height in a slickwater stage#

100-mesh sand (d_p = 150 μm, ρ_s = 2,650 kg/m³) pumped at 0.5 ppa in slickwater (μ = 3 cP, ρ_f = 1,005 kg/m³) into a vertical fracture 200 m long × 30 m tall. Question: what bank height settles out, and what fraction of the fracture footprint stays propped?

Example 8 — Induced-seismicity Mmax screen for a saltwater-disposal well#

An SWD operator in the Delaware Basin plans to inject 50,000 bbl/day for 30 days into a basement-coupled formation. Question: what is the McGarr volumetric upper bound on the largest event the cumulative injection could trigger, and which severity band does it fall in?

Example 9 — Black-oil PVT for a 35°API Bakken oil at downhole conditions#

A Middle-Bakken producer flowing 35°API oil with gas gravity γg = 0.75 at BHST = 240 °F and bubble-point pressure pb = 2,500 psia. Question: at downhole flowing pressure p_wf = 4,000 psia (above bubble point), what are Rs, Bo, and oil compressibility co — and how would they change at p_wf = 1,800 psia (below bubble point)?

Example 10 — Casing collapse + burst check on 5½-in 17 lb/ft P-110 production string#

A Permian operator runs 5½-in OD × 0.304-in wall P-110 (yield = 110,000 psi) production casing to 9,500 ft TVD. Loads at the worst joint: collapse 6,200 psi (full evacuation), burst 9,800 psi (frac with 0.65-psi/ft fluid + 1,500 psi surface), axial 350,000 lbf (hanging weight + fluid drag). Question: does it pass API design factors, and what are the safety factors?

When you sweep a parameter in a sensitivity (DS) run, this is the math the solver evaluates. Each equation lists the UI field that drives it so you know exactly what changing K_IC, C_L, or E does.

6.1 Fracture initiation (breakdown pressure)#

6.2 Mode-I fracture toughness (propagation criterion)#

6.3 Carter leak-off (fluid loss to matrix)#

6.4 Wellbore hydrostatic pressure#

6.4b Temperature-dependent fluid rheology (Arrhenius decay)#

6.5 PKN fracture width (height-contained model)#

6.6 Proppant transport (settling velocity, Stokes)#

6.6b Boycott tilt enhancement#

6.7 Stress shadow (Sneddon)#

6.7 Inclined wellbore breakdown correction (Hubbert-Willis full form)#

6.8 DFIT K_IC fit objective (Carter II substituted)#

6.9 Power-law PKN wellbore width (extends 6.1 to non-Newtonian fluids)#

6.10 Forchheimer non-Darcy pressure drop in the propped pack#

6.11 1-D fracture temperature profile (couples to breaker schedule)#

6.12 Stokes settling with Francis-Boycott wall correction and Richardson-Zaki hindered settling#

1. From the Workspace dashboard, click Sensitivity → New DS run.
2. Pick the parameters to sweep. The Bakken template pre-populates K_IC, C_L, and Young's modulus with realistic ranges.
3. Choose sweep type: Latin Hypercube (recommended), Full factorial, or 1-at-a-time.
4. Set the response metric — e.g. 'Final propped half-length [ft]' or 'Treating pressure peak [psi]'.
5. Click Queue. The DS scheduler launches one simulation per design point.
6. When complete, open Results → Sensitivity tornado to see which parameter has the biggest impact on your response metric.

8.1 Live Pumping (/live-pumping)#

Plan-vs-actual overlay with role-banded stages (Pre-flush · Pad · Slurry · Post-flush) and a real-time screen-out risk pill. Streams via WebSocket, REST polling, WITSML, DAS or DTS — pick the transport from the picker chip group. WITSML uses Basic-auth + ?startIndex= cursor; per-workspace credentials are saved locally.

• Wellbore displacement strip — live SVG showing pumped banks with first-sand-at-perfs + flush ETA chips. Export pad-clock CSV from the strip.
• Nolte-Smith net-pressure panel — log(Pnet) vs log(t) with auto slope-classified Mode I/II/III/IV chip. Save per-job closure/window presets.
• Decline analysis — tabbed √t / log-log / G-function with closure pick + η + regime classifier (normal · PDL · height-recession · post-shut-in growth).
• Step-down auto-detect — finds ≥3 descending plateaus and chips remediation (healthy-entry · add-shots · ball-out · drop-prop slug).
• Net-pressure history-match — 5-knob panel (Γ₂ tip, complexity vol/open/leak, prop drag, TSO backfill) overlays modeled vs observed Pnet. 3 deck-preset buttons.
• ISIP auto-pick — sustained pre-pump + ≥3-of-next-5 zero-rate gate; median BHP over hammer+window with confidence chip. One-click 'Apply to Nolte-Smith'.
• Live auto-history-match — re-fits the 6 net-pressure knobs every 2-30 s from the rolling buffer (coordinate descent on rmsResidualPsi, clamped to slider envelope).
• DAS/DTS waterfall — depth × time heatmap mounted between Live Pumping and Wellbore Displacement.

8.2 Field measurements (WFT/DST/DFIT)#

Builder header → Field data → 4-step paste-CSV wizard. Vendor-neutral wireline / drillstem / mini-frac import; per-workspace storage. The Pressure Advisor warnings panel cross-checks modeled hydrostatic vs measured P (and modeled MW vs measured ρ) with engineer-entered uncertainty bands and ok/watch/amber severity.

8.3 RTA (/rta)#

Blasingame log-log + Agarwal-Gardner semi-log charts with persisted cadence overlay. Named cadence presets, late-window BDF slope diagnosis, and PI/HCPV/R² fit. Arps DCA card bins loaded (t,q) samples to monthly buckets and shows model + R² + EUR(50 yr). Probabilistic EUR runs Fast (≤200) / High (≥2000) Monte Carlo with live progress bar + cancel; σ-qi/Di/b/dMin + samples + seed are persisted.

9.1 Sensitivity & optimization#

• Diagnostic Studies (/diagnostic) — Pnet + screen-out tornado with troubleshooting presets and 'Pull from live stream' cross-link.
• OFAT sensitivity sweep (/sensitivity-sweep) — one-factor-at-a-time response curves; CSV export.
• Optimum Finder — Nelder-Mead + Particle-Swarm with per-algorithm penalty overrides, infeasibility-avoidance presets (off · fast-explore · soft · balanced · strict · aggressive · custom), and a compatibility validator that blocks the Find button on misconfigurations.
• Sweep frontier — weighted-sum / ε-constraint Pareto sweep across saved optima.
• Sensitivity Results visuals — Find Optimum (max/min), clickable factor cross-plots, breakeven overlay, one-click PDF, cross-workspace tornado overlay.

9.2 Parent-child interference (/parent-child)#

• Analytical frac-hit screening: log-radial Δp + Eaton Δσ_h + asymmetry + bashing-risk chip. Plan-view SVG, per-stage table, summary chips, CSV export.
• Microseismic catalog ingest — alias headers, P-percentile drainage-radius fit per parent, faint purple events overlay.
• Regional presets — Permian-Wolfcamp / Bakken-Middle / Eagle Ford / Marcellus-Dry one-click layouts.
• Production timeline — per-parent (start, Δp_∞, τ) + child pump date drives Δp = Δp_∞·(1 − exp(−Δt/τ)).
• Multi-well stress shadow — Sneddon Δσ on aligned stage midpoints + plan-view ✕ markers.
• Poroelastic full tensor — Geertsma 2-D Δσ_h/Δσ_H + SHmax rotation with severity chip and rotated SHmax ticks.
• 3-D Mindlin layered extension — multi-bench depth attenuation; collapses byte-identically to 2-D when no layers.
• Volumetric frac-hit estimate — per-stage proppant + fluid mass arriving at parents (swept-ellipse capture × depletion attraction, Σ ≤ 1).
• Child fracture geometry coupling — bend angle β, tip deflection L·sin(β), bend direction; sensitivity sweeps + Monte Carlo P10/P50/P90.
• Probe-point validator — click-to-add ✕ pins; table shows σ_h_min @ probe + L_a/L_b/asym%.
• Time-varying thermal patches — pump-up/shut-in cooling schedule (start/stop, ΔT, diffusivity, recovery τ) feeds the σh evaluator.
• Runtime SHmax→geometry t-loop — Pump time slider on the far-field card walks the time-resolved σh into child-fracture geometry.

9.3 Field validation campaigns#

Workspace-scoped module at /field-validation. Upload measured (t,P,T) gauges or (MD,P,T) gradient surveys; attach DFIT residuals + Pressure Advisor cross-checks; verdict = AND of attached comparisons. Inline FractureValidationPanel runs PKN/KGD/Radial net-pressure + optional Carter/B-C falloff vs measured BHP and highlights the lowest-RMSE kind.

9.4 DCA + Economics (/economics)#

Three tabs: Arps DCA fit (4 regional type curves) · cascade · NPV/IRR + tornado. EUR uplift publishes to /refrac. Cross-links to /rta for Probabilistic EUR (P10/P50/P90).

9.5 Auto-HM → Forecast pipeline (/auto-forecast)#

One-click orchestration of monthly production history → fitArpsToHistory → monteCarloEur → AI narrative. Sidebar: Predict → 'Auto-HM → Forecast'. Inputs: production history (one volume per line), horizon years, MC sample count, seed, σ on qi/Di/b/dMin. Outputs: fitted Arps kind/qi/Di/b/MAE/R² + P10/P50/P90/mean/std EUR chips + 4-6 bullet narrative card. See §9.4 (Arps DCA) and §8.3 (Probabilistic EUR) for the underlying math — this page is the workflow that wires them together.

• Run controls — the Run button prefetches the heavy arpsDca module on hover/focus, shows a spinner and disables itself while prefetch or compute is in flight, and surfaces a Cancel button alongside.
• Cancel safety — Cancel opens a confirmation dialog so an in-progress run is not discarded by accident. Esc keeps it running; Enter confirms the cancel. A stale-run token guards against late results from a cancelled compute leaking into the UI.

10.1 Reservoir export#

Builder Export → GRDECL (Eclipse) and RESQML v2.0.1 (.epc). RESQML emits CRS + IjkGrid + 3 baseline ContinuousProperty parts (pressure psi, porosity, permeability mD) + optional extras (temperature, saturation, NTG, …). Deterministic UUIDs from a seed give byte-stable output. A built-in validator runs the structural checks Petrel/RESinsight enforce.

10.2 Transient wellbore (Builder preview)#

1-D segmented pipe with implicit-Euler segregated solver (mass + momentum + energy; Swamee-Jain Darcy-Weisbach friction). Opt-in two-way wellbore-storage feedback under-relaxes the bottom-face rate (α=0.5) into the kernel. The Builder Wellbore preview also runs an α stability frontier across [0.1, 0.3, 0.5, 0.7, 1.0] and recommends the smoothest α whose total iterations stay within 25 % of the cheapest.

10.3 Drift-flux multiphase wellbore#

Pure Zuber-Findlay closures wired in via opt-in `multiphase` input. Gas-EOS-coupled mixture compressibility (ρ·c_t)_m now ships with baked-in Standing-Katz Z(p,T) (Dranchuk-Abou-Kassem 1975 + Sutton 1985 pseudo-criticals + Wichert-Aziz 1972 sour-gas correction) — opt in via `multiphase.gasEos.useStandingKatz: true` with optional gas gravity / H₂S / CO₂ mole fractions. Collapses to ideal-gas in the low-p limit. Deferred: full flow-pattern map regime classifier and OLGA-class transient multiphase (out of scope).

10.4 Fluids — breaker schedule + FracPro slurry library#

Builder Fluid model panel ships a Breaker Schedule card (5-entry catalog APS/SPS/Encap/Enzyme/HT-Ox; Arrhenius T½ doubles per 18 °F; first-order μ(t) decay; gel-damage chip). The FracPro-style slurry library (52 role-tagged entries spanning preflush/pad/slurry/postflush — incl. delayed-borate XL, mud acid 12-3, gelled & emulsified acids, cationic HVFR for produced water, HEC frac-pack, methanol-water blend, VES, hybrid slickwater, oil-based, and foam energised systems) feeds a stage-role chip filter; ρ_eff (slurry + proppant @ Cppa) cascades into Pressure Advisor mud weight → hydrostatic / ECD / surface budget / breakdown. The authoritative count comes from `STANDARD_SLURRY_LIBRARY.length` in `src/lib/hfaSlurryLibrary.ts` — if that number ever drifts from what this chapter says, the library is the source of truth and this sentence is stale.

10.4b Fluid name resolution#

10.5 Perf-cluster designer#

Head-bisection split with stress bias per cluster; recommends perf count to achieve limited-entry (default min Δp_perf ≥ 500 psi).

10.6 Layer tracers + LAS → static model + adsorption#

• Layer Tracers wizard — per-layer initialization table + 'produced fraction by layer' Results card.
• LAS → Static model — equal-thickness binning to layer means; em-dash for null bins.
• Langmuir adsorption — V_L·p/(P_L+p); per-layer error+warning chain; per-workspace flag.

10.7 Pad scheduler + ML surrogate + joint history-match#

• Pad scheduler — resource-constrained multi-well Gantt packer (crew/pump/sand pools, per-well earliest start, zipper-stagger helper).
• ML surrogate — quadratic response-surface (ridge normal eqs) for sub-second sensitivity OFAT.
• Joint history-match auto-tuner — Nelder-Mead coordinate descent or PSO swarm over the 2N (shift, scale) vector; safety-guarded so RMSE never increases.

• Calibration report (PDF + CSV) — Inputs · Assumptions · fitted T₀/K_IC · wellbore hydrostatic snapshot.
• FracPro-style report (PDF + CSV) — 17-section Hydraulic Fracture Analysis output (Cover + Tables 1-22).
• Scenario JSON IO — versioned, Zod-validated, per-kind round-trippable wizard scenarios; v1 files auto-upgrade.
• Input bookmarks — generic schema-less Save/Load on Planar3D Comparator and Optimum Finder panels.
• Wellbore CSV import + re-export — auto delimiter detection, alias headers, em-dash → NaN, streaming blob round-trip.

• Reservoir type chip — per-workspace Unconventional|Geothermal toggle gates Heat-extraction Results, EGS buttons (Cold injection, Seismicity advisor), and the Pressure Advisor cooling-credit overlay.
• Table density — Default / Dense toggle in the header; preference is remembered across sessions and auto-applies on simulation + diagnostics views.
• Tools menu (⌘K / Ctrl-K) — Units, Precision, Per-quantity precision mapping, Export current view, KaTeX status, Check for updates, Reset cache. Each item has a tooltip explaining what it does.
• Units everywhere — every field label carries units in brackets (e.g. `Wellhead x-position [ft]`). Missing numerics render as — (em-dash) in both UI and CSV/LAS exports, never 0.

Every field label in the app carries its unit in brackets (e.g. `Wellhead x-position [ft]`). Internally, calculations run in the canonical units below; on-screen values are converted to your chosen display system.

Units glossary#

Input sanity checks#

When you type a value into a field, the app runs a two-tier check. Hard bounds reject the value (clearly non-physical, e.g. negative depth). Soft bounds accept it but warn — they are the lever we use to catch unit-confusion (e.g. typing 50 in a depth-ft field probably means 50 m).

15.1 Non-planar 3D fracture solver (/non-planar-3d)#

Curving-surface DDM3D kernel with tip-kinking + natural-fracture branching, out-of-plane tilt, and T-junction reconvergence weld. Builder Fracture-options panel ends with a Non-Planar 3D solver section (enable · element size [ft] · max kink [°] · branch threshold [°] · max curvature [°/ft] · stress-driven curvature switch · Reset). Per-simulation Results tab mounts a step-scoreboard (rank by Kink / Growth / Opening, bar-norm By-metric / Shared-kink) with winner highlighting.

15.2 Microseismic-calibrated conductivity validation#

Card on /non-planar-3d. CSV-in for modeled k·w cloud and MS discs (moment-tensor-inverted shape from /parent-child stress inversion). Computes coverage fraction (per-disc nearest-sample k·w ≥ threshold) and contrast ratio (mean k·w inside vs outside MS discs); verdict passes when coverage ≥ 0.6 AND contrast ≥ 2.0. Exports a validation CSV.

15.3 Carreau-Yasuda + multi-mode rheology + shear-history breakdown#

• Carreau-Yasuda transition knob `aTransition` (default 2 ≡ legacy Carreau byte-identical; 0.5–1.0 sharpens the knee for HVFR / x-linked gels).
• Generalised Maxwell modes — adds `μ_k/(1+(λ_k γ̇)²)` to matrix viscosity; surfaces Oldroyd-B first normal stress N1 and Weissenberg number Wi (chip warns when Wi > 1).
• Shear-history crosslinker breakdown — integrates D(t) = 1 − exp(−∫(γ̇/γ̇_crit)^m dt) along the pump schedule with optional first-order recovery τ. 4-entry catalog: borate-guar (reversible), zirconate-CMHPG (irreversible), HPG-CMHPG (slow recovery), slickwater HVFR (irreversible).
• BreakerScheduleCard 'Apply shear-history damage' switch shortens T½ proportional to (1 − D), floored at 0.1× to prevent zero half-lives. FluidMixturePanel RheologyCrosslinkerChip shows a `· D X%` suffix when damage > 5%.

15.4 Refrac diversion designer (/refrac)#

Bottom of /refrac — particulate-bridge diverter (PBD) catalog with 6 grades + chemical staging. Boltzmann intake split, log-normal PSD plug-probability, multi-cycle survival, optional chemical Δp_div boost. CSV export via buildRefracDiversionCsv.

15.5 DAS → pump closed loop + DAS → cluster-geometry inversion#

• DAS-pump closed loop panel on /live-pumping (under DAS intake panels) — advisory hold / rate-cut / advance-stage from per-cluster DAS efficiency. Bounded by `maxRateStepBpm`, hysteresis via `stableSamples`, 200-entry audit log, optional Auto-apply switch.
• DAS → cluster geometry inversion — inverts DAS intake fractions to per-cluster efficiencies ε_i (geo-mean = 1), feeds back into the cluster flow trace and produces PKN half-length scaling L_i / L̄ = (V_i/V̄)^(2/3)·ε^(1/3).

15.6 Scenario branching tree (/branches) + cell-level blame#

• Git-style fork tree at /projects/$p/workspaces/$w/branches — SVG forest with lane×depth layout, cycle-break, orphan detection. Fork / diff / Builder actions reuse copySimulation and the builder-compare route.
• SimDiffDialog gains a Blame column — per-leaf author + relative time, per-author filter, 'Snapshot left | right' buttons, and a tracked-versions chip. History persisted via scenarioVersionsStore (≤200 per simId).

15.7 LLM copilot palette (⌘K)#

Natural-language → command routing on top of the ⌘K command palette. ✨ Sparkles button runs the copilot on-demand and renders 'Copilot picks' above the lexical 'Best matches' with reason + score. Powered by Lovable AI Gateway (google/gemini-2.5-flash, JSON-only system prompt).

15.8 Live-ops additions#

• Proppant dune overlay panel — Stokes v_s + Richardson-Zaki + Boycott-tilt enhancement; bank fraction N_s = v_eff·L/(u·h); good / ok / risk severity chip + 5 stats from the latest sample.
• Live field snapshot & share — one-tap card on /live-field producing a URL-safe encoded snapshot link and a PDF cover with advisory banner, window rows, reasons, and note. Read-only viewer at /live-field/snapshot (noindex).

15.9 Probabilistic fracture bundle (/probabilistic-geometry)#

Additive UQ extension: P10/P50/P90 bands for fracture conductivity Cf = k·w and surface treating pressure (closure + Pnet + Δp_pipe + Δp_perf − hydrostatic) + per-factor Spearman tornadoes. Power-law PKN width via optional widthModel/n′/K′ (omitted ≡ Newtonian ≡ legacy byte-identical).

15.10 Completion Quality Index (/completion-quality)#

Per-stage 0–100 score + A-F grade rollup of perf-cluster design, parent-child asymmetry, Mohr slip-tendency, and Nolte-Smith mode. Default weights 0.35 / 0.25 / 0.20 / 0.20 (renormalised on missing inputs). Grade-tinted badges + driver chips + CSV export.

15.11 Coiled tubing / snubbing + geosteering optimizer#

• /coiled-tubing — Lubinski sinusoidal + Dawson-Paslay helical buckling thresholds, regime classifier (none / sinusoidal / helical / lockup), first-lockup MD. Snubbing crossover from F_po = A_p·(p_wh − p_pipe) − buoyed weight − stripper drag.
• /geosteering — composite objective 0.5·quality + 0.3·SHmax-alignment + 0.2·containment − DLS-penalty; minimum-curvature buildup feasibility flag; ranked-results table.

15.12 Multi-well artificial-lift design (/artificial-lift)#

Closes the Prosper/Pipesim parity gap. Composite IPR (linear PI + Vogel), avg-density VLP with GLR uplift + slippage friction, gas-lift fixed-point solver, ESP / rod-pump / plunger screens, and a greedy water-fill allocation across a shared compressor with per-well caps.

15.13 Moment-tensor inversion → DFN#

From the microseismic catalog ingest. Aki-Richards 4.30 spherical→Cartesian, Vavryčuk ISO/DC/CLVD decomposition via 3×3 Jacobi, nodal planes from T/P-axes, Brune source radius r = (7M₀/16Δσ)^(1/3), Mardia clustering on fault normals → DfnFracture-shaped discs (azimuth = strike + 90°). Feeds /non-planar-3d's MS-conductivity validation.

15.14 Phase 9 — thermo-mechanical-hydraulic kernel#

Segregated implicit T → P → σ_h grid (thermoPoroGrid3D) with β-pressure source and Geertsma Δσ_h. Optional Cartesian off-diagonal shear tensor Δσ_xy/Δσ_xz/Δσ_yz via shearTensor.enabled (off by default ≡ byte-identical to legacy diagonal-only). PI-controlled coupled-transient substepper (runCoupledTransientStimulation) wraps stepThermoPoro3D with adaptive dt control and time-varying source/BC callbacks; substep records flag rejections + clamped-at-min steps.

15.15 Surrogate-trained pad-design auto-tuner#

Chains the ML surrogate predictor with the pad scheduler — tunePadDesign sweeps a per-stage Cartesian grid over surrogate ranges (≤4096 default, axis-by-axis fallback above cap), maps best y → durationMin and best x → pool demand, then hands tuned PadStages to schedulePad.

15.16 Black-oil numerics — Sprint A (Pc + TVD) & Sprint B (fully-implicit)#

• Sprint A — opt-in BlackOilNumericsOptions: capillaryPressure?.{pcOilWaterPsi(sw), pcGasOilPsi(sg)} is subtracted/added on water/gas flux Δp; saturationScheme?: 'upwind' | 'tvd-van-leer' reconstructs face Sw via van-Leer ψ(r)=2r/(1+r) with ΣS=1 renorm. Both default OFF ⇒ legacy IMPES byte-identical (≥9 decimals).
• Sprint B — coupling: 'impes' | 'fully-implicit' + fullyImplicit?.{maxNewtonIter=10, tolPressurePsi=0.1, tolSaturation=1e-4, relaxation?}. Re-enters stepBlackOil3P Picard-style until tols met; routes PVT / rel-perm / upwind / BHP reads through the latest iterate. Surfaces newtonIterations / newtonConverged / residuals.
• Side-by-side surfaces: Diagnostics tab NumericsComparatorCard + /numerics-validation SI-vs-FI harness.

15.17 Reservoir kernel extensions (v6 batch)#

• Black-oil tracers with PVT partitioning — voxel-grid passive scalars riding on the 3-phase IMPES kernel. Per cell/species: φ_α = (K_α·S_α)/Σ → c_α = φ_α·m/V_α → upstream flux. Wells inject at tracerInjection / produce at cell-average c. Independent multi-tracer (water / gas / inhibitor / energized-CO₂); optional first-order decay.
• 1D-submesh water banking — per-fracture-face log-spaced radial submesh resolves Sw(r,t) during leakoff + flowback with internal CFL substepping and optional imbibition pull-back. Mass balance < 2% on no-clamp scenarios.
• Black-oil fluid regions (PVTNUM-style) — per-region (Bo, Rs, μ_o, Bg, Bw, μ_w) tables routed per-cell via FluidRegionAssignment; applyFluidRegionOverrides masks AABB compartments.
• Zero-permeability cubes — applyZeroPermCubes masks AABB cubes of permMd to 0; harmonic-mean TPFA faces collapse, never mutates input.
• Per-well drilling-time schedule — WellActivation 4-phase classifier (idle / drilling / production / shut-in) with linear ramp ⇒ Newton-safe turn-on, dt substepper splits on well events.
• Compositional 3-phase BO wiring — new 'compositional-3p' FluidKind in FluidModelPanel (Sw / Sg / Swc + PR-EOS energized-CO₂ gas-FVF bridge); default kind unchanged.
• RESQML EPC export + schema validator + golden fixture — alongside GRDECL; opt-in extra ContinuousProperty parts (temperature / saturation / NTG / …); validateResqmlEpc catches every structural check Petrel / RESinsight enforce.

15.18 Live perforation erosion + auto-HM thermal effect#

• Live perforation erosion panel — §8.12 asymmetric Du / Ds / Dd / Cd with spatially-correlated α field (mulberry32 + Box-Muller + exp-decay smoothing); user-tunable σ_α / correlation length [ft] / seed persisted in perfErosionUncertaintyStore. Limited-entry chip from min Δp_perf on the eroded geometry vs 500 psi target. Traces NOT persisted — pure-derived from samples × prefs so replay is byte-identical.
• Live auto-HM thermal effect — opt-in μ(T) drift on the interval fit. Constant thermalScale ≠ 1 slides the fit-window location along μ^(1/4) without changing the loss-surface shape; thermalOutOfBand is advisory-only. Both coord-descent and Bayesian backends route through forwardNetPressure (never inline μ(T) per-backend). Off-collapse drift-guarded.

15.19 Petrophysics & completions additions#

• Mineralogy log interpretation — GR → IGR → V_sh via Larionov-tertiary / Larionov-older / Steiber / Clavier / linear; density-neutron crossplot RMS porosity; 3-mineral Cramer-solve inversion (quartz / carbonate / clay) on [1; ρ_b; PEF] with component clipping + matrix renorm + all-clay fallback. autoGrBaselines picks 5th / 95th percentile when ≥5 GR samples. Drops straight into lasToStaticModel.
• StageOpt wellbore proppant transport — stage-level algebraic allocator splitting proppant across clusters via Stokes-number turning efficiency η_turn = 1/(1 + St·k_inertia) + per-segment Daneshy survival exp(−v_s·L/(h·v_w)). Mass conservation Σperf + Σbed = pumped ± 1e-6 lb. CoV severity ladder ok ≤ 0.20 / watch ≤ 0.40 / amber ≤ 0.70 / critical.
• Stress-conductivity coverage + embedment chip — in ProppantLibraryPicker, ISO-13503-5 knot badge + ok / watch / extrapolating chip keyed to closure stress + rock E. 'Apply to k·w scale' writes the embedment factor (Cooke / Lacy (E_rock/E_ref)^0.5, clamped (0.05, 1]) into override.kwScale.

15.20 Builder Wells & Fracture-options additions#

• Bedding-plane fracture card (Fracture-options panel) — two-criterion Mohr-Coulomb classifier (vertical when p > σh; horizontal when p > σv − (τ_max − c)/μ_b; mixed within mixedBandPsi). Height-growth efficiency penalty H(n) = clamp(0.1 + 0.9·exp(−0.5·n), 0.1, 1). 4-play preset catalog (Vaca Muerta / Utica / Montney / deep Bakken).
• Mud-window card (Wells panel header) — Drillworks / Baker-GMI / Techlog-MEM parity. 4-limit window: pore-pressure floor (kick), Kirsch + Mohr-Coulomb shear-failure floor (breakout, closed-form q = (1 + sinφ)/(1 − sinφ)), σ_v loss ceiling, tensile breakdown ceiling p_w = 3σ_h − σ_H − α·p_p + T₀. Severity ok ≥ 1 / watch ≥ 0.3 / amber ≥ 0 / critical < 0 ppg + per-stage rollup from perfs[].mdFt.

15.21 v5 physics batch (8 modules)#

• Horizontal / bedding-plane fracture — see 15.20.
• Rate-and-state friction — Dieterich-Ruina (lab-granite defaults); criticalStiffness / nucleationLength helpers; classifyRsfStability strengthening / conditionally-stable / unstable; spring-slider simulateRateStateSlider with optional injection pore-pressure ramp.
• Gas non-Darcy inflow + advisory on gasLift — Wattenbarger D = 2.222e-15·γ·k/(μ·rw·hp²); Δψ = A·q + B·q² solver; classifyNonDarcyLoss ok / watch / amber / critical (5/15/30%); gasNonDarcyAdvisory composes Hawkins + perforation skin via gasInflowRateWithSkin.
• Stress-dependent permeability with hysteresis — Terzaghi effective stress; exponential or power-law loading; unloading anchors at peakStress with shallower γ_unload; residualFraction cap; classifyStressPermLoss ok / watch / amber / critical (10 / 30 / 60%).
• Relative permeability + capillary pressure — Corey / LET 2005 / Stone-II 3-phase oil; Brooks-Corey drainage P_c = P_e·S_we^(−1/λ) capped at maxPc; Skjaeveland mixed-wet sign-changing curve.
• Mineral scaling kinetics — MINERAL_DB (calcite / barite / FeS / SiO₂) with log10 Ksp 25 °C, Arrhenius (k_ref, Ea), TST σ/n, IAP stoichiometry. Davies-extended activity coefficient (I ≲ 0.5); saturationIndex SI = log10(IAP / Ksp); tstRate r = −k·A·sgn(1 − Ω^σ)·|1 − Ω^σ|^n; classifyScaleRisk ok / watch / amber / critical (French Creek 0.3 / 1.0 bands).
• Wellbore-stability mud-window — see 15.20.
• Formation damage & skin + IPR ↔ skin integration — Hawkins damage skin; Karakas-Tariq 1991 perforation skin (5 phasings from Economides Table 6-1); productivity ratio PR = ln(r_e/r_w) / (ln(r_e/r_w) + s); composeSkin sum + severity ok ≤ 0 / watch ≤ 5 / amber ≤ 20 / critical. Optional skin? block on WellLiftInputs auto-scales linear-PI + Vogel rate via PR; gasInflowRateWithSkin composes into the A·q + B·q² solver.

15.22 3D viewer (/viewer-3d & /viewer-3d/scientific)#

• Renders wellbore + stages + wings + offset wells from any simulation; severity-tinted by per-stage Completion Quality Index.
• View presets 1–4 (overhead / heel / cross-section / iso); R resets the camera; drag to orbit.
• Layer toggles (wellbore / stages / wings / offsets) and per-severity visibility chips; settings persisted via viewer3DPrefsStore.
• Growth scrubber — Space toggles play / pause (resets fraction at end); [ / ] step ±5%; readout shows visible/total stages + percent.
• Scene stats HUD + 'Copy stats' button (clipboard-friendly multiline summary with sim ID, wellbore length, stage / wing / offset counts, severity breakdown).
• Share-view URL preserves camera + toggles via hash params; Fullscreen toggle on the canvas wrapper.
• Exports: PNG snapshot, glTF, OBJ; AI 'Explain this scene' summary via Lovable AI Gateway.

15.23 v6 Tier-2 Track B — laminated-shale + CO₂-storage assurance#

• Phase-field / DEM laminated shale (/phase-field-dem & /phase-field-shale) — AT-1/AT-2 damage with irreversible history field, cohesive Mode-I/II traction-separation, He-Hutchinson 1989 kink-vs-pierce classifier (bedding-plane NFs), MTS kink-angle, and σh-degradation hook into the Geertsma engine. PhaseFieldFeedbackCard on /parent-child wires applyPhaseFieldFeedback (per-stage damage amplitude → σh derate) into runShmaxGeometryTimeLoop with monotone-stable σh slices; a parameter-sweep harness (runPhaseFieldFeedbackSweep) reports per-stage + worst stability rollups and exports two CSVs.
• Anisotropic-elasticity (TIV) — Thomsen 1986 ε/γ/δ → C_ij → engineering moduli {E_h, E_v, ν_h, ν_v, G_v, G_h} + directional E(θ). Wired into ddm3D + non-planar pipeline + DFN config + LaminatedShaleResultsCard.
• Proppant DEM at tip (Hertz-Mindlin bridging) — pure F_n = 4/3·E*·√R*·δ^1.5 + Coulomb-capped Mindlin tangent + N_b = w/d bridging factor + σ_rock = η·I·p_net tip-stress transfer. Wired into nonPlanar3D/pipeline.ts (B3b shipped); StepScoreboard renders a Tip-bridging column with amber tint when bridging active.
• CO₂ storage assurance (/co2-storage) — Nordbotten-Celia √t plume radius, Theis log-time over-pressure, caprock capillary seal classifier (ok / watch / amber / critical), Coulomb-failure margin, solubility / mineral / residual trapping ramps, and Darcy line-source leakage flux.

15.24 OLGA-class transient multiphase wellbore (Phase B + Phase 8)#

• Taitel-Dukler + Barnea flow-regime map — 7 regimes per segment (horizontal TD / vertical Barnea incl. churn) with marginLog for near-boundary chips.
• Enthalpy-wave solver — 1-D implicit advection-diffusion on (ρh): backward-Euler tridiag with upwind convection, Joule-Thomson, latent-heat-of-vaporisation, wall U-value coupling.
• Drift-flux multiphase wellbore — pure Zuber-Findlay closures wired into transientWellbore via opt-in WellboreStepInput.multiphase; gas-EOS-coupled (ρ·c_t)_m mixture storage; Standing-Katz Z(p,T) via DAK 1975 reduced-density Newton + Sutton 1985 pseudo-criticals + Wichert-Aziz 1972 sour-gas correction (opt-in standingKatzOptions).
• Two-way wellbore-storage feedback (Phase 8 inc 3) + α stability frontier sweep (inc 4) on the Builder Wellbore preview — 3rd collapsible card runs the synthetic ramp across DEFAULT_ALPHA_GRID, picks the smoothest α whose totalIters ≤ 1.25× the cheapest, and exposes an 'Apply recommended α' button that writes back into transientWellboreCouplingStore.
• Transient multiphase run history (Phase B inc 22–25) on /transient-multiphase-wellbore — localStorage ring buffer (cap 8) of completed runs with compare-vs-current table, A/B diff modal (changed-inputs + 7-metric ↑better/↓worse), CSV import/export (buildRunHistoryCsv + mergeRunHistory), and 6-tile sparkline trend strip (oldest → newest, Δ chip colored by improvement direction).

15.25 Phase-field σh-degradation in the runtime time loop (Track B inc B4)#

Optional per-stage phase-field damage feeds back into runShmaxGeometryTimeLoop via applyPhaseFieldFeedback + nearest-stage σh degradation in the runtime evaluator: clamped [0,1], padded / truncated, monotonic-stable across slices. Companion parameter-sweep harness (runPhaseFieldFeedbackSweep) walks a damage-amplitude grid and produces per-stage + worst stability rollups (monotone σh, max Δσh jump, bend growth, finite) plus two CSV builders.

15.26 Induced-seismicity forecaster + TLP suite (Phase F)#

• Pore-pressure → seismicity rate (Dieterich 1994) — backward-Euler γ + Δτ coseismic jump + TLP traffic-light classifier (green / yellow / amber / red).
• /induced-seismicity route — USGS catalog auto-refresh (7 cadences, decideAutoRefresh honours in-flight + document-hidden), TLP threshold preset catalog (default / OK_CC / KS_CC / TX_RRC / custom) with monotonic-ladder sanitiser, and an operator-action audit log (append-only cap-500 FIFO, CSV export). Auto-logs TLP transitions; manual rate-cut / shut-in / monitoring / regulator-report / note actions.

15.27 MRV — Subpart RR + field-validation cross-check (Phase D)#

• MRV Subpart RR report (/ccus-mrv) — 4 §-keyed sections + attestation + hash-chain proof + period-filtered ledger tail; async exportMrvSubpartRrPdf (lazy jspdf, letter, paginated) wired into the summary card with operator / facility / facility-id inputs.
• MRV ↔ field-validation cross-check card — Δp residual stats + severity ladder + ok → operator-note / watch+ → alert event builder + CSV parser. Closes Phase D.

15.28 Runtime SHmax → geometry time loop (M2) + time-varying thermal patches#

• runShmaxGeometryTimeLoop — LIVE on /parent-child via 'Pump time t [yr]' slider backed by m2TimeSliderStore. Drift-guard probePointVsThermoPoroParity covers 466 cases (extended with t-axis × effectiveDrawdownPsi(timeline, pumpDateIso) per-parent timelines).
• Time-varying thermal patches (Phase 1d) — per-patch injection schedule (start / stop ISO, peak ΔT, diffusivity ft²/day, recovery τ days, optional max radius). Cold zone evolves through pump-up (r = √(D·t_inj), ΔT = peak) and shut-in (r keeps spreading, ΔT = peak·exp(−t_post/τ)). Merged with static patches per slice and fed into BOTH analyzePoroelastic calls (main + runtime σh evaluator). Depletion-only collapses byte-identically.
• Per-workspace UI prefs (°F / °C + ft²/day / m²/day) via thermalPatchUnitsStore; storage stays canonical.

15.29 Trust gates — analytical-gate trio + grid-convergence#

• Analytical-gate trio — McWhorter-Sunada 1-D capillary imbibition + Morel-Seytoux 2-D five-spot areal sweep + Theis radial pressure transient. Three pure libs + 26 drift-guards; closes the gaps beyond Buckley-Leverett.
• Grid-convergence suite (/grid-convergence) — runs the kernel at nx0 / 2·nx0 / 4·nx0 × upwind / TVD, reports observed order p, and rolls up FI convergence + worst mass-balance % into the TrustRollupChip on /numerics-validation and the NumericsComparatorCard header (ok < 0.5% / watch < 2% / review otherwise). Broadened with 3 regime scenarios (shock / capillary / compressible) + recommendScheme(run) heuristic.
• Black-oil trust gates — pure Buckley-Leverett (Corey fw + Welge tangent + profile sampler + L1/L∞ comparator) and mass-balance report (phaseInPlace via kernel pvtAt + per-step absolute / relative residual incl. worstRelative). Kernel parity drift-guard locks IMPES + TVD L∞ ≤ 0.5 vs BL.

15.30 Phase 16 — coupling-direction promoted default-ON#

reservoirCouplingStore default flipped false → true + new mirror blackOil3PCouplingStore (default true, key downhole.dfit.blackOil3PCoupling.v1). SolverPreferencesCard gains a 2nd Switch row for blackOil3PCoupling. /solver-spec scoreboard coupling-direction row promoted next-up → shipped. Explicit setEnabled(false) overrides persist so users who turned coupling off pre-promotion keep that choice (only the 'absent localStorage entry' branch flips).

15.31 Design Copilot ↔ fleet priors (Phase E)#

/design-copilot 'Fleet priors' card — basin Input + 'Loosen to fleet P10/P90' Switch + live tightening-preview chips. Calls tightenDesignFactorsFromBasin to clamp design-factor ranges toward measured P10/P90 from the regional fleet, with a sonner toast on Run.

15.32 Voice-First surfaces + readback dock#

• Global floating readback dock — bottom-right PTT button that routes spoken questions to the most recently active results-bearing surface (RTA, Economics, Optimizer). Uses a pub/sub context store so the active surface always wins; hides when no surface is active or the Web Speech API is unavailable.
• Voice dictation for numeric fields — inline mic button next to any numeric input. parseDictatedQuantity handles number words, decimals, units (bpm/psi/ppm/ppa/ppg/gpm/bbl/gal/lb/ft/in/m/kpa/mpa/F/C/%), and 'k/M' suffixes. Drop-in component: DictateNumericFieldButton.
• Results readback intent matcher — classifyResultsQuery scores each metric by matched-pattern character length; answerResultsQuery composes a speakable utterance and pipes it into the TTS engine. Per-surface metric registries for RTA, Economics, and Optimizer.
• Audio cue mute controls — circular mute/unmute toggle in VoiceReadbackDock plus the 'M' keyboard shortcut; both immediately update the audio cue store and the UI stays in sync via a manual subscription mechanism.

15.33 Copilot v2 — streaming, memory, search, tools#

• Streaming responses in CopilotDrawer — ReadableStream + getReader(), with an AbortController and a Stop button so users can cancel mid-generation; partial output is preserved with a ⏹ Stopped marker.
• Per-page / per-simulation chat history — threads are scoped by context key (e.g. ws_<id>/sim_<id>) and automatically restore when you return to the same page or simulation.
• History search and filtering inside the drawer — query filter, role filter, recency filter, match highlighting via HighlightedText, and hit counts. Powered by copilotThreadSearch.
• Copilot tool registry — 7 safe app-side tools (jumpToPanel, applyKnob, runOptimum, runSweep, saveBookmark, openSimulation, appendActivityLog) with Zod inputSchemas, needsApproval gates, and caller-injected executors. UI wiring deferred to the Engineer/Driller Copilot toolsets.

15.34 Driller's Copilot (RigSense)#

• Six-tab driller-facing AI co-pilot at /driller-copilot — Stuck-pipe early warning, Kick/loss + dynamic mud window, MSE founder advisor, Trip swab/surge advisor, Voice Q&A, and Auto morning report.
• Pure diagnostic engines under src/lib/driller/ — stuckPipeEarlyWarning (differential / mechanical / pack-off proxies), kickLossDetector (flow surplus + pit gain + live mud-window margins), mseFounderAdvisor (Teale MSE regime classifier + WOB/RPM step recommendation), tripSwabSurgeAdvisor (Burkhardt Δp + dynamic effective MW + bisected max-safe pipe velocity).
• LocalStorage RAG corpus for offset reports — offsetReportsStore + lexical searchOffsetReports; aiDrillerCopilotContext caps the payload at 8 KB. askDrillerCopilot server function calls Lovable AI Gateway (google/gemini-2.5-flash, JSON-only system prompt, 10 s timeout).

15.35 Wellbore sensitivity suite#

• FracCADE-style depth ladder at /projects/$p/workspaces/$w/wellbore-sensitivity — Quick (5-factor tornado) and Custom (engineer-picked factors with ±1–90% swings) across three domains: Well path, Completion, and Tubing. Persistence via wellboreSensitivityDepthStore.
• Saved scenarios panel — per-workspace named configurations stored in localStorage; save, load, rename, and delete. Scenarios encode the depth ladder + factor selections + per-factor swings. Export CSV header: Factor,Units,Low value,High value,Low metric,High metric,Swing,|Swing|.
• Shareable scenario links — any saved scenario can be shared via a base64url-encoded URL payload; the recipient lands on the same workspace surface with the scenario loaded.
• Dual-scenario comparison at /wellbore-sensitivity/compare — side-by-side picker, diff table highlighting changed values, and an 'unchanged' toggle. Dual-scenario sharing via URL hash (#compareA=...&compareB=...). The last compared pair is restored per workspace from localStorage.

15.36 Global navigation — Help drawer + Command palette#

• Searchable Help drawer (⌘?) — manual search, recent pages, and quick links. Mirrors the /manual route content without leaving the current page.
• Command palette (⌘K) — hybrid lexical + semantic command ranking. The ✨ Sparkles button runs the LLM copilot on-demand and renders 'Copilot picks' above the lexical 'Best matches' with reason + score. Built on commandPaletteHybridSearch and commandCopilot.

15.37 Validated wellbore pressure sandbox#

• Interactive sandbox at /sandbox/wellbore-pressure — live form, hydrostatic / temperature / wellbore pressure breakdown grid, and per-field validation. Runs the same wellborePressureEngine used elsewhere in the app.
• Industry-validated test suite — 24 SPE/IAPWS reference cases, 39 edge-case tests, and 8 seeded fuzz tests covering hydrostatic, temperature, and wellbore pressure calculations.
• WellborePressureResult fields documented in docs/wellbore-pressure-result.md; bottomholePressurePsi is aliased as bhpPsi for API alignment. Sandbox state is shareable via base64url-encoded URL.

Manual v1.4 (June 2026) consolidates every feature shipped since v1.3 (May 2026). The detailed deep-dives live in §15.32–15.37; this section is the at-a-glance changelog you can scan in 60 seconds.

Highlights#

Shipped features by track#

Default behavior changes (read carefully)#

Migration notes#

• No schema migrations required — every new store uses a fresh localStorage key.
• Voice-First surfaces are opt-in by browser capability (Web Speech API). The dock and inline mic buttons render null when the API is unavailable.
• Copilot chat history is scoped by page/simulation context; existing chats without a context key remain in the default global thread.
• Wellbore sensitivity scenarios and comparison pairs are stored per workspace; shared links are ephemeral and do not write to the recipient's saved scenarios.

Each derivation below maps an equation in the kernel to its textbook source so an engineer can audit the call site, the assumptions, and the validity band in one pass. The /trust/analytical-verification dashboard scores cases 1-3 against these formulas every build, and the /physics-gaps-v8 dashboard surfaces the live verification-mode chip (history-matched vs. independent).

18.1 KGD half-length (verification case 1)#

18.2 PKN width and length (verification case 2)#

18.3 Radial-toughness penny-fracture (verification case 3)#

18.4 Dual-porosity Warren-Root (Gap 2a)#

18.5 Palmer-Mansoori swelling (Gap 2b)#

18.6 Slurry density and tip screen-out (Gap 3)#

18.7 Near-wellbore tortuosity Δp (Gap 4)#

18.8 Boundary conditions (Gap 5)#

Manual v1.7 (July 2026) captures the physics + workflow batch that closed the v4/v5/v6 competitor-gap audits and the Phase 15 rheology upgrade. Deep-dives live in the linked routes; this section is the at-a-glance changelog.

Highlights#

• Non-planar 3D fracture solver — surface-mesh DDM with tip kinking, natural-fracture branching, out-of-plane tilt, and T-junction reconvergence weld (see /non-planar-3d + per-simulation Results tab).
• Compositional 3-phase black-oil kernel wired into the Fluid model panel (energized-CO₂ PR-EOS bridge, IMPES + tracers + fluid regions + zero-perm cubes + per-well drilling times).
• Multi-well pad artificial-lift design (gas lift / ESP / rod pump / plunger) at /artificial-lift with shared-compressor allocation.
• Coiled-tubing & snubbing reach analyzer at /coiled-tubing (Lubinski + Dawson-Paslay buckling) and geosteering optimizer at /geosteering (SHmax alignment + containment + DLS feasibility).
• Refrac diversion designer (PBD + chemical staging, multi-cycle survival) mounted on /refrac.
• v5 rock+fluid physics bundle: bedding-plane fracture card, mud-window card, formation-damage + perforation skin, rate-and-state friction, stress-dependent permeability with hysteresis, LET / Stone-II rel-perm, mineral scaling kinetics, gas non-Darcy inflow.
• Phase 15 rheology upgrade: Carreau-Yasuda with optional Maxwell modes + crosslinker shear-history damage folded into the breaker schedule.
• Scenario branching tree at /branches (git-style fork/diff) and cell-level scenario blame in SimDiff.
• LLM Copilot picks in the ⌘K Command palette (Gemini 2.5 Flash via Lovable AI Gateway).
• RESQML v2.0.1 EPC export validated against a golden fixture — round-trippable in Petrel / RESinsight.

Shipped features by track#

Default behavior changes (read carefully)#

Migration notes#

• Fluid kind now includes 'compositional-3p' in addition to black-oil; existing simulations keep their current kind and default to black-oil.
• Non-planar 3D results are appended to each simulation as an extra Results tab when the solver is enabled; disabling reverts to the planar Results view.
• The bedding-plane card mounts at the end of Fracture options — existing tutorial snapshots that assert panel length were regenerated in the same edit.
• Command palette 'Copilot picks' require LOVABLE_API_KEY (Lovable Cloud users have this pre-set); without it the ✨ button is hidden and only lexical matches show.

Manual v1.8 documents the operator-facing surfaces and advanced-physics routes shipped after the v6 competitor-gap closure. Every route below is live in production; the walkthroughs mirror the on-screen tabs and cards so a new engineer can go from cold-open to a defensible answer without a mentor.

20.1 Driller's Copilot (RigSense) — /driller-copilot#

Six-tab driller-facing assistant that watches the rig telemetry stream and calls out stuck-pipe risk, kick/loss, MSE founder, swab/surge, and answers voice questions. All physics is pure — the AI layer (Lovable AI Gateway, Gemini 2.5 Flash) is used only for Q&A and morning report drafting, never for a setter action.

20.2 Live+ diagnostics pack — /live-pumping + /tools/dfit-interpreter#

Sprint 1 of the v10 competitor-gap plan. Adds a step-down inverter, per-cluster entry-friction distribution, DFIT pre-closure regime interpreter, and a wellbore fluid-front animator. The pre-closure interpreter is also mounted at the public /tools/dfit-interpreter free tool (no auth, no storage).

20.3 Transient multiphase wellbore — /transient-multiphase-wellbore#

Phase B coordinator that steps pressure → flow-regime → enthalpy in one call. Wraps the drift-flux 1-D solver (Standing-Katz Z(p,T) via DAK + Sutton + Wichert-Aziz sour-gas correction) with a Taitel-Dukler + Barnea flow-regime classifier and a backward-Euler enthalpy wave (Joule-Thomson + latent heat of vaporization).

20.4 CCUS / MRV ledger — /ccus-mrv#

Regulator-grade Monitoring / Reporting / Verification workflow for CO₂ storage. Append-only signed ledger of injection mass, plume snapshots, caprock seal severity, and leakage flux; Subpart RR-style PDF export per reporting period; hash-chain proof and field-validation cross-check between measured and modeled Δp.

20.5 Induced-seismicity forecaster — /induced-seismicity#

Dieterich (1994) seismicity-rate response to a pore-pressure time series with a Traffic-Light Protocol (TLP) classifier, USGS catalog auto-refresh, operator-action audit log, and copy-paste regulator templates (OK CC, KS Corp Comm, TX RRC).

20.6 Non-planar 3D fracture solver — /non-planar-3d + Results tab#

Surface-mesh DDM with tip kinking (M-integral MTS), natural-fracture branching (Renshaw-Pollard + Gu-Weng), out-of-plane tilt, T-junction reconvergence weld, and a kernel bridge that pushes an equivalent planar half-length + conductivity retention back into /refrac, black-oil, and /parent-child. Opt-in from the Fracture options panel; omitted ≡ legacy planar path byte-identical.

20.7 Solver spec scoreboard — /solver-spec#

Refreshed model card. Each physics row carries four possible badges — Shipped, Next up, In Newton loop, Out of scope — and 'In Newton loop' rows expose a hover tooltip pointing at the exact kernel file / PR that wires the module into coupledNewtonStep. A short legend above the scoreboard explains each badge and defines the outer nonlinear corrector.

• Shipped — live in production and exercised by the linked route.
• Next up — physics is built; remaining PR wires it into runtime UI and the Newton outer loop.
• In Newton loop — runs inside coupledNewtonStep (pressure / width / state variables corrected until residuals converge).
• Out of scope — explicitly excluded today (e.g. OLGA-class transient multiphase in the frac kernel).

Version + migration notes#

This chapter exists to close the historical §21 numbering gap. It contains no new physics — it is a signpost. If you are looking for what changed in a specific release, follow the link below; if you are looking for what is still in flight, follow the roadmap link.

• §15 — Recently shipped (post-1.0). The evergreen list; kept up to date as features land.
• §16 — What's new in v1.4 vs v1.3.
• §19 — What's new in v1.7 vs v1.6.
• §20 — What's new in v1.8 (operator surface + advanced physics).
• `.lovable/plan.md` — the working plan tracked alongside the codebase; every open review comment maps to a plan bucket here.
• `/roadmap` — the live status page, sourced from `src/lib/atozGapList.ts`. Ship/flag status is flipped there and in project memory in the same edit, so this is the closest thing to a single source of truth.

Reviewers frequently ask whether Wellbore Genius is only validated against measured field data (history matching). It is not. Every physics module ships with an executable drift-guard test that compares the numerical kernel against a closed-form analytical solution, a published benchmark, or a manufactured solution. If any comparator drifts outside its published tolerance, CI fails and the build is blocked from shipping.

Analytical benchmarks currently in CI#

Field-campaign validation (channel B)#

• DFIT registry — every registered mini-frac closure re-fit each CI run; residuals summarised in solverSpecScoreboard.ts.
• MSEEL HFTS-1 datasets — public microseismic + fibre benchmark cross-references (mem/reference/mseel-hfts1-datasets.md).
• Field-validation campaigns route (/projects/$p/workspaces/$w/field-validation) — upload gauge (t, P, T) or gradient (MD, P, T) surveys; verdict = AND of attached comparisons (leak-off, fracture-mechanics, DFIT).
• Microseismic ↔ conductivity validation (mem/features/microseismic-conductivity-validation.md).
• PVT consortium presets exercised against published Wolfcamp / Bakken / Eagle Ford / Marcellus / Montney / Vaca Muerta EoS tunings.

How to read /solver-spec#

The /solver-spec page is the human-readable index of what is verified vs what is roadmap. Each row states (a) the current implementation, (b) the drift-guard file that locks it, (c) the honest limits (what the module does NOT do), and (d) the next roadmap increment. If a row's `roadmap` cell is non-empty, that gap has an open test but no shipping implementation — the review should treat it as absent, not present.

Depth-profile visual — DFIT calibration#

Depth-profile visual — wellbore mud-window#

This chapter exists because reviewer feedback repeatedly said 'the improvements are not visible in the manual'. Every module below is already shipping — links point to the live route and the pure-lib source. If a claim here is not backed by a drift-guard test file, treat it as a documentation bug and file it.

23.1 Non-planar 3D fracture solver#

23.2 Thermo-poro 3-D coupling#

23.3 Phase-field DEM for laminated shale#

23.4 Compositional 3-phase black-oil with energized CO₂#

23.5 Adaptive coupled-transient substepper (Phase 9)#

23.6 Heterogeneity → propagation coupling#

The Gaussian random-field multiplier on K_IC, σ_h, k, and φ (route /heterogeneity) feeds the fracture propagation solver directly. On each tip-advance, the local field value is sampled at the tip location, multiplied against the base property, and used in the next Griffith / Perkins criterion. This closes the gap the round-2 review flagged ('heterogeneity overlay exists but not coupled to main propagation solver').

23.7 Multi-well interference (consolidated)#

Four routes cover the parent-child interference story end-to-end: (a) /parent-child — log-radial Δp + Eaton Δσ_h + asymmetry; (b) stress-shadow overlay — Sneddon Δσ from sibling wells; (c) poroelastic depletion — full-tensor Δσ_h / Δσ_H + SHmax rotation; (d) Mindlin 3-D bench — layered vertical attenuation. All four share the same PoroelasticResult shape so a per-stage table row lists every contribution side-by-side. Runtime SHmax → child-fracture geometry loop is documented under (M2) of the thermo-poro parity bridge.

23.8 Rate-and-state friction + induced-seismicity traffic light#

23.9 What this chapter does NOT cover#

• 3-D viewer improvements (cross-section slice, HUD read-out, playback contour, propagation trails, kink-node dots, NF-activation flash, tip-velocity bloom scale) — tracked in the roadmap at /roadmap?phase=viz and cross-checked against `.lovable/plan.md` §1/§4. Every item there is either LIVE or has a named owning file.
• Results-tab completeness pass (ISIP marker, closure-pressure reference line, fluid-efficiency, half-length / height vs. time) — tracked in /roadmap?phase=viz under the Results-tab lane.
• AI chatbot integration — separate product decision, not a physics module; status at /roadmap?phase=polish.
• Full A-to-Z gap list (all series, both shipped and in-flight) is at /roadmap.

This chapter answers three questions engineers keep asking during reviews: (1) what assumptions does the kernel actually make; (2) how are the PDEs discretized in space and time; (3) how are field-unit inputs (ppg, psi, bbl/min, °F) converted before they reach the solver. The last section walks through the three specialty material presets (sodium nitrate, flour/epoxy, black-powder residue) and shows the exact line of physics each one changes.

24.1 Governing assumptions (what every solver takes for granted)#

• Linear poroelasticity with Biot coefficient α ∈ [0, 1]; effective stress σ' = σ − α·p_p. Non-linear (plastic) response is layered in via Mohr-Coulomb yield only where explicitly enabled (mud-window solver, rate-and-state fault).
• Isothermal single-phase flow unless a module states otherwise. Thermal coupling is opt-in per module (thermo-poro 3-D, live-auto-HM thermal effect, DFIT temperature-dependent viscosity).
• Newtonian fluid rheology by default. Non-Newtonian branches (Carreau-Yasuda, Herschel-Bulkley, Maxwell modes) are explicit user choices and are byte-identical to Newtonian when their extra parameters collapse (n=1, τ_y=0, no modes).
• Rock is treated as a continuum at the grid scale; discrete fracture networks (DFNs) are represented as graph elements, NOT as embedded XFEM enrichments. The frac solver couples DDM tips to a graph dispatcher (see /solver-spec).
• Gravity is vertical (−ẑ). Deviated / horizontal wells project weight onto the wellbore-axial direction inside the mud-window and hydrostatic solvers.
• All comparators run on the pure physics module. UI-level wiring is verified separately by Playwright drift-guards, not by the analytical tests.

24.2 Discretization — what scheme is used where#

The kernel is a mix of analytical, semi-analytical, and numerical solvers. The tables below say which method is used for which module so a reviewer can jump straight to the right drift-guard.

24.3 Unit conventions (field-first, converted at the boundary)#

Every UI input is field-unit. Conversions happen at exactly one place per module (the `*ToSi` helper) so a reviewer can grep for the boundary. The kernel itself is SI internally except where an industry-standard equation is more legible in field units (e.g. 0.052·ρ·TVD for hydrostatic pressure).

24.4 Specialty material inputs (how each preset feeds the kernel)#

The three material presets (sodium nitrate, flour/epoxy diverter, black-powder residue tracer) are solute-only. None of them injects energetic mass or exothermic chemistry into the kernel. Below is a preset-by-preset breakdown of what each input actually changes, what it does NOT change, and which drift-guards lock that behaviour.

24.4.1 Sodium nitrate (NaNO₃) — tracer / scale-control additive#

• concPpm (50–5 000 ppm) → passive solute concentration on the fluid stream. Solver treats NaNO₃ as non-reactive: no Δρ correction beyond the linear brine-density hook, no exothermic source term, no Ksp check.
• fluidTempF (60–250 °F) → clipped into the μ(T) look-up used by the live-auto-HM thermal effect. Outside the band the preset gate refuses to accept the input.
• bottomholePsi (1 000–12 000 psi) → informational; validates the requested envelope against the tracer band.
• mudWeightPpg (8.3–14 ppg) → routed through the standard hydrostatic hook 0.052·ρ·TVD; there is NO separate oxidiser-loading branch.
• What it does NOT do: no combustion, no radical chemistry, no automatic coupling to the scaling-kinetics module (scalingKinetics.ts) unless the operator opts in via the Water solutes panel.

24.4.2 Flour / epoxy diverter — degradable mechanical diverter#

• concPpm (100–20 000 ppm) → inert-solid mass loading. Feeds the effective slurry density used by slurryHydrostatic.ts and the friction-factor bump in livePumping.ts.
• fluidTempF (70–200 °F) → gates the epoxy-cure window; outside this band the acknowledgement checkbox is disabled.
• bottomholePsi (1 500–11 000 psi) → informational; validates the diversion-mechanics envelope.
• mudWeightPpg (8.3–13 ppg) → hydrostatic scaling only. Heavier muds outside the band trigger a realism warning because the diverter washes through perforations.
• What it does NOT do: no degradation kinetics, no time-dependent plug strength, no coupling to the perforation-erosion model. The diverter is a constant inert loading for the duration of the stage.

24.4.4 Sensitivity callouts — how small input swings move the depth-profile outputs#

The callouts below apply a ±10% perturbation to each preset input and report the resulting change in the hydrostatic column, geotherm, or bottomhole-pressure envelope at a 10,000 ft TVD reference. Values are computed by `materialPresetSensitivity.ts` and rendered from the same evaluators the depth-profile charts use, so the sweep is byte-consistent with the visualization examples in Section 24.3.

24.4.3 Black-powder residue tracer — passive post-perforating marker#

• concPpm (1–250 ppm) → passive marker concentration only. The preset explicitly refuses to accept energetic-mass inputs; live-charge sizing must be done by the perforating provider outside this app.
• fluidTempF (60–300 °F) → routed through the same μ(T) look-up as the other tracer.
• bottomholePsi (1 000–14 000 psi) → informational; captures the typical perforating BHP envelope.
• mudWeightPpg (8.3–15 ppg) → hydrostatic scaling only.
• What it does NOT do: no pyrotechnic chemistry, no detonation-shock coupling into the DDM tip solver, no coupling to the microseismic moment-tensor engine. The marker is thermally and mechanically inert in the kernel.

24.5 Hard limitations of this chapter#

These cases are deliberately small so a reviewer can rework them in a spreadsheet in under two minutes. Each case cites (a) the manual equation number from Chapter 24, (b) the traceability item from Chapter 22 (model verification) or Chapter 23 (recent physics), and (c) the exact drift-guard file under src/lib/__tests__/ that asserts the expected value.

25.1 Case A — Hydrostatic pressure (single-fluid column)#

1. Inputs: ρ = 9.8 ppg (water-based brine), TVD = 10 000 ft.
2. Apply the equation: p_h = 0.052 · 9.8 · 10 000 = 5 096 psi.
3. Cross-check the SI form: ρ_SI = 9.8 · 119.826 = 1 174.29 kg/m³; TVD_SI = 10 000 · 0.3048 = 3 048 m; p_h_SI = 1 174.29 · 9.80665 · 3 048 = 35 106 kPa = 5 091 psi (0.1 % rounding vs. the field short form — matches Chapter 24.3).
4. Expected output: 5 096 psi at the bottom of the column.
5. Traceability: equation 24.1 unit-conversion row (hydrostatic short form); asserted in src/lib/__tests__/slurryHydrostatic.test.ts and src/lib/__tests__/ballisticsWellHydrostatic.test.ts (same 0.052 constant, TVD-projected).

25.2 Case B — Theis line-source drawdown at a parent well#

1. Inputs (SI): q = 0.01 m³/s, μ = 1e-3 Pa·s, k = 1e-13 m² (~ 100 md), h = 30 m, r = 500 m, t = 5 years = 1.577e8 s, φ = 0.10, c_t = 1e-9 1/Pa.
2. Compute the u numerator: r²·φ·μ·c_t = 250 000 · 0.10 · 1e-3 · 1e-9 = 2.5e-8.
3. Compute the u denominator: 4·k·t = 4 · 1e-13 · 1.577e8 = 6.308e-5.
4. Combine: u = 2.5e-8 / 6.308e-5 = 3.964e-4 (i.e. u ≪ 1, deep in the late-time / log-approximation regime).
5. Full W(u) via the Abramowitz-Stegun 5.1.11 series (matches expIntegralE1 in crossWellTomography.ts): W(u) = −γ − ln(u) − Σ_{n≥1} (−u)ⁿ / (n · n!). With u = 3.964e-4, ln(u) = −7.8339, so the leading term is −γ − ln(u) = −0.5772 + 7.8339 = 7.2567. The n=1 correction is −(−u)/1 = +u = 3.96e-4; n=2 is −u²/4 ≈ −3.9e-8; higher terms are < 1e-11. Sum: W(u) ≈ 7.2567 + 3.96e-4 ≈ 7.2571.
6. Cross-check the small-u log branch: for u ≲ 0.01 the series collapses to W(u) ≈ −γ − ln(u), which reproduces 7.2567 within 0.01 % — this is the PASS branch the drift-guard exercises (no lookup table needed).
7. Apply Theis: Δp = (q·μ) / (4·π·k·h) · W(u) = (0.01 · 1e-3) / (4·π · 1e-13 · 30) · 7.2571 = 1e-5 / 3.770e-11 · 7.2571 = 2.653e5 · 7.2571 = 1.925e6 Pa.
8. Convert: Δp = 1.925e6 / 6 894.757 ≈ 279 psi.
9. Expected output: ~279 psi drawdown at r = 500 m after 5 years — deep enough into the log branch that expIntegralE1(u) and the −γ − ln(u) shortcut agree to four decimals.
10. Traceability: equation 24.1 (radial diffusivity); Chapter 23 recent-physics item for multi-well interference; expIntegralE1 in src/lib/crossWellTomography.ts; asserted in src/lib/__tests__/parentChildInterference.test.ts (Theis log-radial branch) and src/lib/__tests__/crossWellTomography.test.ts (Theis superposition).

25.3 Case C — Nordgren PKN half-length at late time#

1. Inputs: E = 30 GPa, ν = 0.25 → E' = 30e9 / (1 − 0.0625) = 32.0 GPa; q = 0.05 m³/s (~ 27 bpm one-wing); μ = 0.1 Pa·s (100 cp cross-linked gel); h = 30 m; t = 3 600 s (60 min pump time).
2. Compute the group inside the fifth root: E'·q³/(μ·h⁴) = 32.0e9 · (0.05)³ / (0.1 · 30⁴) = 32.0e9 · 1.25e-4 / (0.1 · 810 000) = 4.00e6 / 81 000 = 49.4.
3. Fifth root: 49.4^{1/5} = exp(ln(49.4)/5) = exp(3.90/5) = exp(0.780) = 2.181.
4. Time factor: t^{4/5} = 3600^{0.8} = exp(0.8 · ln 3600) = exp(0.8 · 8.189) = exp(6.551) = 700.6.
5. L = 0.68 · 2.181 · 700.6 ≈ 1 039 m ≈ 3 410 ft one-wing half-length.
6. Expected output: ~1 040 m half-length at t = 60 min for the tuned Bakken-like inputs.
7. Traceability: equation 24.4 (DDM tip system — Nordgren asymptote is the analytical envelope of the DDM solver); Chapter 22 model-verification item for the analytical PKN reference; asserted in src/lib/__tests__/analyticalFractureModels.test.ts.

25.4 Case D — Mud-window shear-failure floor (Kirsch + Mohr-Coulomb)#

1. Inputs: σ_H = 10 000 psi, σ_h = 7 500 psi, UCS = 4 000 psi, φ = 30° → sin φ = 0.5, q = 1.5 / 0.5 = 3.0. α = 0.8, p_p = 4 500 psi.
2. Right-hand side: 3·σ_H − σ_h − UCS − α·p_p·(1 − q) = 30 000 − 7 500 − 4 000 − 0.8·4 500·(1 − 3) = 30 000 − 7 500 − 4 000 + 7 200 = 25 700 psi.
3. Solve for the minimum p_w: p_w ≥ 25 700 / (1 + q) = 25 700 / 4 = 6 425 psi.
4. Convert to a mud weight at TVD = 10 000 ft: ρ_min = p_w / (0.052 · TVD) = 6 425 / 520 = 12.36 ppg. Anything below 12.36 ppg triggers the shear-failure floor.
5. Expected output: floor mud weight ≈ 12.36 ppg at 10 000 ft TVD for these stress inputs.
6. Traceability: equation 24.5 (mud-window solver); Chapter 22 verification item for the deviated first-crossing scan; asserted in src/lib/__tests__/wellboreStabilityMudWindow.test.ts (vertical closed form) and src/lib/__tests__/wellboreStabilityMudWindowDeviated.test.ts (high-p_w regression + first-crossing scan added in this round).

25.5 Case E — Arps hyperbolic decline EUR#

1. Inputs: q_i = 800 bbl/d, D_i = 0.85 /yr, b = 0.6, q_ab = 20 bbl/d.
2. Convert q_i to a yearly basis: q_i_yr = 800 · 365 = 292 000 bbl/yr.
3. Rate ratio: (q_ab / q_i)^{1−b} = (20 / 800)^{0.4} = 0.025^{0.4} = exp(0.4 · ln 0.025) = exp(−1.476) = 0.2287.
4. Bracket: 1 − 0.2287 = 0.7713.
5. EUR = q_i_yr / ((1 − b)·D_i) · bracket = 292 000 / (0.4 · 0.85) · 0.7713 = 858 824 · 0.7713 ≈ 662 400 bbl.
6. Expected output: EUR ≈ 6.6e5 bbl for the tuned Bakken-tier hyperbolic inputs.
7. Traceability: Chapter 23 recent-physics DCA item; equation 24.2 (mass-balance branch — Arps is the analytical envelope of the material-balance decline); asserted in src/lib/__tests__/arpsDca.test.ts (hyperbolic branch + EUR) and src/lib/__tests__/arpsMonteCarlo.test.ts (probabilistic EUR).

25.6 How to add a new worked case#

• Pick one equation from Chapter 24 (equations 24.1 – 24.5). If the equation isn't there yet, add it to Chapter 24 first so the traceability chain stays intact.
• Author the case as an `equation` block (with `usedIn`, `assumptions`, `validity`) followed by a `steps` block that walks a reviewer from inputs → arithmetic → expected output → test file.
• Cite the exact drift-guard filename under src/lib/__tests__/. If none exists, add one in the same PR — a worked case without a test is not a verification case.
• Keep the numbers small enough to rework in a spreadsheet in ≲ 2 minutes; anything larger belongs in the benchmark harness, not the manual.

25.7 Hard limitations of this chapter#

This chapter is the reader's index — pick a symbol or acronym, follow the chapter marker, land on the defining equation or worked example. Chapter numbers below are the printed §-numbers you see in headings (§1 through §28 are contiguous; §21 is the release-notes index that closes the historical numbering gap).

26.1 Greek symbols#

• α (Biot coefficient) — effective-stress splitter σ' = σ − α·p. Defined §6 (Physics & equations), used §11 (poroelastic depletion) and §25 Case A/B.
• β (Forchheimer inertial coefficient) — non-Darcy pack term dP/dL = μv/k + βρv². Registry in §11 (advanced physics), audit in §22 (model verification).
• γ̇ (shear rate, 1/s) — Newtonian γ̇ = 8v/d, Carreau/CY μ(γ̇) surface. Defined §6, extended in §11 (Carreau-Yasuda + Maxwell modes).
• Δσ_h, Δσ_H (stress-shadow tensor components, psi) — Sneddon + Geertsma poroelastic Δσ. Derived §6, applied §11 (parent-child).
• ε (cluster efficiency, geo-mean = 1) — DAS-inverted intake fraction. §9 (Live operations) and §11 (DAS → geometry inversion).
• η (hydraulic diffusivity k/(φμc_t), ft²/s) — controls τ_D. Defined §6, used in dimensionless-time drift-guards §23.
• κ (Mardia concentration parameter) — greedy fault-set clustering. §11 (moment-tensor inversion → DFN).
• μ (fluid viscosity, cp) — appears in every leakoff/Darcy/inflow formula. Defined §6, referenced end-to-end.
• ν (Poisson's ratio) — Sneddon/Geertsma kernels. §6 and §11.
• ρ (density, ppg or kg/m³) — hydrostatic column. §25 Case A hydrostatic worked example.
• σ_h, σ_H, σ_v (principal stresses, psi) — Mohr/breakout envelope. §6 (physics) + §24 (mud-window derivation) + §25 Case E.
• τ (relaxation time, s / recovery time in crosslinker gels) — Maxwell mode τ_k and gel recovery τ_rec. §11 (rheology & crosslinker).
• φ (porosity, fraction) — appears in η, in invasion radius, in mass balance. §6 + §22 (mass-balance report).
• ψ (pseudo-pressure, psi²/cp) — gas-inflow Δψ = A·q + B·q². §11 (gas non-Darcy inflow).

26.2 Acronyms & product terms#

• BHP — bottom-hole pressure. Reported everywhere; see §9 (live operations) for the live-stream convention.
• BL — Buckley-Leverett fractional-flow benchmark. §22 (black-oil trust gates).
• CQI — Completion Quality Index (0–100 + A–F grade). §10 (sensitivity & completion).
• DAS / DTS — distributed acoustic / temperature sensing. §9 (live operations, fiber-optic transports).
• DCA — decline-curve analysis (Arps qi/Di/b + P10/P50/P90 EUR). §10 (economics) + §9 (RTA).
• DFIT — diagnostic fracture-injection test. Walkthrough §3, calibration wizard §5 Example 1.
• DFN — discrete fracture network. §6 (UFM-class DFN dispatcher) + §11 (moment-tensor → DFN).
• DDM3D — displacement-discontinuity method, 3-D non-planar kernel. §11 (Non-Planar 3D) + §23 (bridge to planar kernel).
• EUR — estimated ultimate recovery. §10 (Arps DCA + MC bands).
• FVF — formation volume factor (Bo, Bg). §5 Example 9 (black-oil PVT).
• GRI — Gas Research Institute public dataset. §22 (public-benchmark DFIT comparison).
• HF vs NF — hydraulic vs natural fracture. §11 (bedding-plane fracture) + Viewer 3D right-rail toggle.
• IPR / VLP — inflow / vertical-lift performance. §11 (artificial lift & non-Darcy skin).
• ISIP — instantaneous shut-in pressure. §9 (auto-pick, live operations).
• K_IC — mode-I fracture toughness (MPa·√m). Fit in §5 Example 1 (DFIT), used §6.
• MW — mud weight (ppg). §14 (units & sanity) + §25 Case A.
• OFAT — one-factor-at-a-time sweep. §7 (sensitivity) + §10 (optimizer suite).
• PKN / KGD / Radial — classical fracture geometry models. §6 physics + §22 verification.
• PVT — pressure/volume/temperature (black-oil correlations). §5 Example 9 + §11.
• RSF — rate-and-state friction. §11 (induced-seismicity advanced physics).
• RTA — rate-transient analysis (Blasingame / Agarwal-Gardner). §9.
• SHmax — maximum horizontal stress azimuth. §6 (Hubbert-Willis tensor) + §5 Example 5 (inversion).
• SI — saturation index (log10 IAP/Ksp) for mineral scale. §11 (scaling kinetics).
• TSO — tip screen-out. §9 (net-pressure match).
• UFM — unconventional fracture model. Called out in the honest-scope note in §6.
• WITSML — wellsite information transfer standard. §9 (telemetry transports).

26.3 Chapter markers used in cross-references#

When prose says 'see §6.2' it means chapter 6, second equation. Chapter numbers are parsed from the leading number of each heading (e.g. '22. Model verification' → §22). Every §-number from §1 through §28 is present — §21 is the release-notes index that closes the historical numbering gap. Equation ordinals restart at 1 inside every chapter, so §6.2 and §11.2 are unrelated.

• §1–§4 — orientation & walkthroughs.
• §5 — worked examples (numbers in, numbers out).
• §6 — core physics & governing equations.
• §7–§10 — sensitivity, calibration, live ops, optimization.
• §11 — reservoir/wellbore/fluids & advanced physics (RSF, non-Darcy, scaling, DDM3D…).
• §12–§14 — reports, exports, workspace toggles, units & sanity.
• §15–§20 — recently-shipped and 'what's new' changelogs.
• §21 — release-notes index (v1.4 / v1.6 / v1.7 / v1.8 cross-links + roadmap pointer; closes the historical numbering gap).
• §22 — model verification (BL, mass-balance, public benchmarks).
• §23 — recent physics + numerical additions (round-3 answers).
• §24 — numerical-method background & specialty material inputs.
• §25 — worked verification case studies (five hand-workable cases).
• §26 — this keyword reference.
• §27 — data-entry patterns (paste-from-Excel, LAS, JSON scenarios, CSV templates, supported file formats).
• §28 — offline & deployment policy (online-first, read-only offline cache, Electron field build, PWA home-screen).

This chapter answers 'what file do I upload where'. Every Builder panel exposes a Paste-from-Excel tab; heavy interchange formats (LAS, WITSML, CMG/ECLIPSE decks) route through dedicated importers. Round-trip anything you build through JSON so a teammate can reproduce your run exactly.

27.1 Paste-from-Excel#

Every non-trivial Builder panel has a Paste-from-Excel tab that accepts a rectangular block copied from Excel / Numbers / Sheets. The panel parser is column-order tolerant when the first row is a header — otherwise it assumes the canonical Bakken-tutorial layout below. Units are always inferred from the bracketed suffix in the header (e.g. 'Perm [md]' vs 'Perm [nD]').

27.2 LAS files (well logs)#

LAS 2.0 / 3.0 ASCII well logs upload from Static model → Curve sets → Import LAS. The parser reads ~V, ~W, ~C, ~P, and ~A sections; ~O (other) is ignored. Depth must be MD in feet or metres — the header UNIT field decides. Non-finite / -999.25 sentinels are converted to null (renders as — in charts).

Multi-well LAS bundles: upload one .zip and every .las inside is parsed with the archive filename as the well tag. Duplicate curve mnemonics are suffixed _2, _3, … so no data is silently dropped.

27.3 Supported file formats#

The master table below is the answer to 'our datafile will be in JSON type only?'. JSON is the native round-trip format, but the app also accepts every heavy interchange format the drilling / completion / reservoir world uses. Anything not listed here should be pasted via §27.1 or converted to CSV.

Python SDK examples for every read-format above live under public/sdk/python/examples/. The examples wrap the same public /api/public/sdk/v1/* endpoints the web app uses, so anything you can do in the UI is scriptable.

27.4 JSON scenario schema#

Scenario files are Zod-validated on read. The envelope is a discriminated union on `kind` (dfit-calibration / expert-job-setup / pressure-advisor / …); each `kind` has its own strict input schema in src/lib/scenarioInputSchemas.ts. Older v1 files auto-upgrade to v2 on load — you never need to edit them by hand. The full schema is published as JSON-Schema at /schemas/scenario.v2.json for external tooling.

• Version envelope: `{ version: 2, kind, inputs, meta: { createdAt, createdBy, appVersion } }`.
• All numeric fields are `number().finite()` — NaN and Infinity are rejected at parse time.
• Missing optional fields fall through to `defaultXxxInputs()` factories (one per kind).
• Round-trip is byte-stable: `parse(build(x)) === x` for every kind (locked by scenarioJsonIo.test.ts).

27.5 CSV templates#

Every Builder panel and every Results / Live / Sensitivity export uses the same dash convention (see §12 exports): missing numerics render as — (em-dash), never 0 or empty. Templates that a user can pre-fill live under public/templates/ and are linked from the matching panel's Paste-from-Excel tab.

• public/templates/history-match-measured-bhp.csv — measured (t [s], BHP [psi]) time series for the /history-match interval-fit tab.
• public/templates/history-match-measured-rate.csv — measured (t [s], rate [bpm]) time series (same fitter).
• public/templates/field-measurements-wft.csv — depth-referenced WFT / DST / DFIT observations for §27.1 field-measurements paste.
• public/templates/microseismic-catalog.csv — (t [s], x [ft], y [ft], z [ft], mag) for the /parent-child ingest.
• public/templates/production-monthly.csv — (date, q_o [stb/d], q_w [stb/d], q_g [Mscf/d]) for the RTA DCA fit.

The short version: the web app is online-first, works read-only offline for scenarios you have already opened, installs to your phone as a home-screen icon (no service worker — no stale-cache traps during a live frac), and has a fully-offline Electron packaging path for field engineers who cannot rely on connectivity.

28.1 Online-first web (default)#

• Team scenarios, versioning, and cross-device sync all live on Lovable Cloud (managed backend). Cloud is REQUIRED for those features.
• Individual workspace state — Builder inputs, chart settings, cadence presets — is mirrored to localStorage per browser, so a network blip does NOT lose your in-flight work.
• Sign-in state is refreshed on tab focus. If you lose Cloud connectivity, the app stays in the current view until you navigate; on next navigation it prompts to reconnect.

28.2 Read-only offline (browser cache)#

• Every scenario you open at least once is available offline via the browser HTTP cache and the localStorage stores keyed under downhole.*.
• Builder + Sensitivity + RTA + Live-pumping REPLAY mode all keep working against localStorage data — no round-trip needed.
• Publishing new scenarios, running server-side sensitivity, and Cloud sync all require connectivity — the app chips these as 'Offline — reconnect to run' rather than failing silently.
• There is no service worker. This is deliberate: a service worker that cached the app shell could keep serving a stale UI during a live frac, which is a safety issue we refuse to accept.

28.3 PWA home-screen (manifest-only)#

• The app ships a Web App Manifest at /manifest.webmanifest with `display: standalone`, a theme colour, and an icon.
• On iOS Safari: Share → Add to Home Screen adds a full-screen app icon. On Android Chrome: three-dot menu → Install app.
• This is manifest-only: no service worker is registered, so 'Add to Home Screen' does NOT enable offline caching. It only gives you an app-style icon and standalone chrome.
• The installed launcher hits the live URL every time — you always see the latest deploy. That is intentional for a field-operations tool.

28.4 Fully-offline field build (Electron)#

• For engineers on frac locations with no reliable connectivity, we ship an Electron desktop packaging path (Windows / macOS / Linux).
• The Electron build bundles the same physics kernels and Builder UI, plus a local scenario store that syncs when the laptop comes back online.
• Cloud-only features (team scenarios, cross-device sync, published sharing links) are chipped as unavailable in the offline build, not silently disabled.
• Contact the Wellbore Genius team for the current Electron installer — the packaging pipeline lives outside this web repo.

28.5 What we deliberately do NOT do#