Wellbore Genius

Documentation

v1.1 · May 2026

Wellbore Genius — User Manual

Build a model from scratch, calibrate from field data, and see every formula running in the background.

Worked examples — numbers in, numbers out

Seven walkthroughs: four end-to-end (Bakken DFIT, Permian surface budget, parent-child screening, live screen-out) plus three calculation-kernel deep dives (stress inversion, embedded DFN transfer, proppant bank height). Realistic field inputs, equations shown, and exact UI routes to reproduce each result.

1. Getting started

How the app is organized: Project → Workspace (a.k.a. Sandbox) → Simulation. The Builder is where you make all changes.

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.

Field labels always show units in brackets

Every input is labelled like `Wellhead x-position [ft]`. If you're unsure what a field means, click the `?` icon next to its label.

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.

Why is Save Changes greyed out?

Save Changes only enables when at least one field has been edited since the last save. If you can't click it, your edits may not have committed to a field — click outside the input first, or check Validate for an error blocking the change.

2. Walkthrough — Bakken tutorial (full)

Build a Bakken model from scratch through all 12 Builder panels, validate, run, and view results — full A-to-Z reference case.

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#

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

Bakken preset values (already loaded)

PVT: Bakken oil + brine. Conductivity multipliers: 100-mesh = 0.6, 40/70 = 1.0. Mesh: 600 ft × 400 ft × 200 ft, 5-ft cells near the well. SHmax azimuth: 42°. DS sensitivity ranges are pre-populated for K_IC, C_L, and Young's modulus.

3. Walkthrough — DFIT calibration

Import field DFIT pressure data, run the calibration wizard, fit T₀ and K_IC, and export the Calibration report (PDF + CSV).

Open the simulation in Builder. Click Calibration in the sidebar (or press G then C).
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]').
The wizard auto-converts to bottomhole pressure using the wellbore hydrostatic snapshot (TVD + fluid density at reservoir temperature).
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.
Review the fitted values in the right rail. The Pressure advisor wizard will use these as defaults next time.
Builder header → Export → 'Calibration report (PDF + CSV)' to save the inputs, assumptions, fitted values, and hydrostatic snapshot for handoff.

Re-use the calibration

The fitted T₀ and K_IC are persisted to the workspace and auto-prefilled into the Pressure advisor and any new simulation in the same workspace. You only fit once per pad.

4. Walkthrough — Pressure advisor + Expert setup

The two main wizards: surface-pressure budget (Pressure advisor) and full job-design scenario JSON IO (Expert setup).

Pressure advisor (4 steps)#

Builder header → Pressure advisor. Auto-prefills TVD from `inputs.mesh` midpoint, reservoir temperature from `inputs.fluid`, and last calibration point.
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.
Step 2 — Mud weight. Convert between ppg and psi/ft. The graph shows hydrostatic vs. depth.
Step 3 — Surface budget. The advisor sums hydrostatic + friction + breakdown - pore to get required surface pressure, then compares against your pump rating.
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.
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.

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

5. Worked examples — numbers in, numbers out

Ten worked examples — four end-to-end workflows (DFIT calibration, surface budget, parent-child screening, live screen-out), three calculation-kernel deep dives (stress inversion, embedded DFN transfer, proppant bank height), and three regulatory / hardware-rating screens (induced-seismicity Mmax, black-oil PVT, casing collapse + burst). Realistic field inputs, the equations the app runs, the numbers it returns, and where to reproduce each one in the UI.

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.

Input	Value	Source
TVD [ft]	10,500	Builder → Wells & perforations
BHST [°F]	240	Builder → Fluid model
Mud weight [ppg]	9.0	Pressure advisor Step 2
Pore pressure P_pore [psi]	5,460	Static model, ≈ 0.52 psi/ft
Picked closure pressure [psi]	7,820	G-function tail, DFIT wizard
Instantaneous shut-in (ISIP) [psi]	8,150	Pressure record

SH_min ≈ P_closure = 7,820 psi ⇒ gradient = 7,820 / 10,500 = 0.745 psi/ft

Minimum horizontal stress is read directly off closure. The gradient is the standard sanity check (Bakken band: 0.70–0.80 psi/ft).

Used in

DFIT calibration — closure fit

Pressure Advisor — Step 4 (Breakdown check)

Static model panel — SH_min prefill

Module

src/lib/dfit.ts → pickClosurePressure

Where

P_closure picked on the G-function plot
TVD from Wells & perforations

Assumptions

Closure picked on G-function (or √t) before pressure-dependent leak-off
Vertical TVD known to ±25 ft (gradient sensitivity)
Single-phase water-equivalent hydrostatic in the wellbore at shut-in

Validity range

Tight unconventional reservoirs; gradient typically 0.65–0.95 psi/ft. Outside this band the pick should be re-checked against offset DFITs.

Units: psi, psi/ft

T₀ = ISIP - SH_min = 8,150 - 7,820 = 330 psi

Tensile strength is the overshoot above SH_min at instantaneous shut-in.

Used in

DFIT calibration — tensile-strength fit

Pressure Advisor — Step 4 (Breakdown check) as P_breakdown = SH_min + T₀ − P_pore

Module

src/lib/dfit.ts → fitTensileStrength

Where

ISIP from the pressure trace
SH_min from closure

Assumptions

ISIP captured within ~10 s of pump-off (water-hammer rejected)
No near-wellbore tortuosity loss already subtracted from ISIP

Validity range

Unconventional tight rock: T₀ usually 100–800 psi. Negative or > 1,500 psi values indicate either a bad ISIP pick or post-breakdown re-pressurization.

Units: psi

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).

Output	Value	Where it lands in the app
Fitted SH_min [psi]	7,820	Static model panel + Pressure advisor prefill
Fitted T₀ [psi]	330	Fracture options panel + Pressure advisor
Fitted K_IC [psi·√in]	≈ 1,090	Fracture options + DS sensitivity default range
Calibration report (PDF + CSV)	1 file pair	Builder → Export

Step-by-step walkthrough — DFIT calibration

1Pick closure on the G-function plot
UI: Builder → Calibration → G-function tab → click the tail break
The G-function curve goes flat once the fracture has fully closed. The break point IS your closure pressure — read it directly off the y-axis at BHP.
Result: P_closure = 7,820 psi
2Read SH_min from closure
Closure pressure equals minimum horizontal stress for any well at this depth. Divide by TVD for the gradient sanity check (Bakken band 0.70–0.80 psi/ft).
SH_min ≈ P_closure ⇒ gradient = SH_min / TVD
Result: SH_min = 7,820 psi · gradient = 7,820 / 10,500 = 0.745 psi/ft ✓
3Compute tensile strength T₀ from ISIP overshoot
Instantaneous shut-in pressure overshoots SH_min by exactly the rock's tensile strength. Read ISIP off the pressure trace at pump-off.
T₀ = ISIP - SH_min
Result: T₀ = 8,150 - 7,820 = 330 psi
4Fit fracture toughness K_IC against the closure tail
UI: Calibration wizard → Apply
The wizard runs a Carter-II falloff least-squares fit on the post-closure tail to back out K_IC. The minimised objective is the squared-residual sum Φ above (see §6.2 for the full module + validity range). Default K_IC search bounds are 0.5–2.5 MPa·√m.
Φ(K_IC, C_L) = Σᵢ [ p_obs(tᵢ) − p_model(tᵢ; K_IC, C_L) ]²
Result: Fitted K_IC ≈ 1.2 MPa·√m (≈ 1,090 psi·√in)
5Push results into the model + export the report
UI: Builder → Static model + Fracture options (auto-prefilled) · Export → Calibration report
The fitted SH_min lands in Static model, T₀ + K_IC in Fracture options, and the wellbore hydrostatic snapshot is captured for the audit trail. The PDF + CSV pair is the deliverable.
Result: 1 PDF + 1 CSV in Builder → Export

Try it yourself

Open any simulation → Builder → Calibration. Use the sample DFIT CSV from the Bakken template (or paste your own). The wizard auto-converts surface pressure to BHP using the wellbore hydrostatic snapshot, so you only need (t, p_surf).

Open unified solver with Bakken DFIT inputs

Bakken DFIT calibration — TVD 10,500 ft, BHST 240 °F, MW 9.0 ppg.

Download preset · Bakken DFIT calibration inputs

JSON bundle of every input above (and the expected outputs). Retype the values into Builder → Calibration to reproduce the calculation step by step.

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?

Input	Value
TVD [ft]	9,800
Mud / pad weight [ppg]	8.5 (slickwater + FR)
Tubular friction gradient [psi/ft]	0.085 @ 80 bpm in 4½-in (Hill DR sigmoid, FR @ 1 gpt)
Perforation friction Δp_perf [psi]	650 (45 perfs × 0.42-in EHD)
SH_min [psi]	7,250
T₀ [psi]	300
Pore pressure P_pore [psi]	5,100

P_hydro = 0.052 × MW × TVD = 0.052 × 8.5 × 9,800 = 4,331 psi

Hydrostatic head pushing back at surface is 'free' pressure — the lower it is, the more surface pressure you need to make up.

Used in

Pressure Advisor — Step 2 (Mud weight)

Pressure Advisor — Step 3 (Surface budget) as the hydrostatic credit

Module

src/lib/pressureAdvisor.ts → hydrostaticPsi

Where

MW = mud weight [ppg]
TVD [ft]

Assumptions

Single-phase, constant-density column (no foam, no slugging)
Vertical TVD (deviated wells use TVD, not MD)
Cooling-credit overlay disabled (geothermal mode adds a ΔT term)

Validity range

Conventional ppg range 7.5–18 ppg; brine/oil-based muds. For slurry-laden columns the FracPro→Pressure cascade overrides MW with effective slurry density ρ_eff.

Units: psi

P_breakdown = SH_min + T₀ - P_pore = 7,250 + 300 - 5,100 = 2,450 psi

Pressure required at the perforation face to initiate a fracture (effective-stress form).

Used in

Pressure Advisor — Step 4 (Breakdown check)

Pressure Advisor — Step 3 (Surface budget) as the lower bound on bottomhole

Module

src/lib/pressureAdvisor.ts → breakdownPressurePsi

Where

SH_min, T₀ from calibration (Example 1 pattern)
P_pore from Static model

Assumptions

Uniaxial reduction of the §6.1 Hubbert-Willis tensor (SH_max ≈ SH_min; no thermal or poroelastic Δσ)
Pre-existing perforation (no rock cohesion term)
Isotropic horizontal stress at the perf depth (ν-corrections lumped into SH_min)

Validity range

Cased + perforated completions. For openhole or oriented perforations, switch to the Kirsch-stress form in the calibration hub.

Units: psi

P_surf = P_breakdown + P_friction + Δp_perf - P_hydro = 2,450 + 0.085·9,800 + 650 - 4,331 = 1,602 psi

Surface budget. The advisor sums breakdown + tubular friction + perf friction, then subtracts the hydrostatic credit.

Used in

Pressure Advisor — Step 3 (Surface budget)

Live Pumping — plan-vs-actual surface pressure curve

Module

src/lib/pressureAdvisor.ts → buildPressureBudget

Where

All four terms from rows above

Driven by (UI fields)

Mud weight (Step 2)
FR concentration (Hill DR sigmoid)
Perf count + EHD (perf-cluster designer)

Assumptions

Steady-state hydrostatic + Darcy-Weisbach friction in the wellbore (no transient water-hammer)
Perf friction via Δp = K·ρ·q²/(N_p·A_p²) with K ≈ 0.20 for clean perfs
FR drag-reduction follows the calibrated Hill sigmoid (frictionReducerCurve.ts)

Validity range

Slickwater and linear-gel jobs at 30–120 bpm. For crosslinked-gel pressure cascades, enable the rheology preview and re-fit DR.

Units: psi

Output	Value	Verdict
Required P_surf [psi]	1,602	Well under the 10,000-psi rating
Headroom [psi]	≈ 8,400	Safe — you can lift rate to ~120 bpm before binding
Recommended action	Hold plan	No mud-weight bump needed

Step-by-step walkthrough — Surface-pressure budget

1Compute hydrostatic head
UI: Pressure advisor → Step 2 (Mud weight)
Mud weight in ppg, TVD in ft, 0.052 is the unit constant for psi. This is the 'free' surface pressure your pad weight gives you.
P_hydro = 0.052 × MW × TVD
Result: P_hydro = 0.052 × 8.5 × 9,800 = 4,331 psi
2Compute breakdown pressure at the perfs
UI: Pressure advisor → Step 4 (Breakdown)
Effective-stress form (uniaxial reduction of the §6.1 Hubbert-Willis tensor — assumes SH_max ≈ SH_min; switch back to the tensor form when horizontal-stress anisotropy is measurable). SH_min and T₀ come from Example 1's calibration; P_pore from Static model.
P_breakdown = SH_min + T₀ - P_pore
Result: P_breakdown = 7,250 + 300 - 5,100 = 2,450 psi
3Estimate friction losses
UI: Builder → Wells & perforations → Perf cluster designer
Tubular friction is rate × DR-curve dependent (Hill sigmoid for FR). Perf friction comes from the n × EHD calculator.
P_friction = grad_friction × MD · Δp_perf from perf-cluster designer
Result: P_friction = 0.085 × 9,800 = 833 psi · Δp_perf = 650 psi
4Sum the surface budget
UI: Pressure advisor → Step 3 (Surface budget)
Required surface pressure to initiate the fracture at design rate. Compare against your pump rating.
P_surf = P_breakdown + P_friction + Δp_perf - P_hydro
Result: P_surf = 2,450 + 833 + 650 - 4,331 = 1,602 psi
5Read headroom + recommended action
UI: Pressure advisor → Step 3 → green/red chip
Headroom = pump_rating - P_surf. The chip turns red live if you exceed rating; green means you have margin to lift rate.
Result: Headroom ≈ 8,400 psi (vs 10,000-psi rating) ⇒ Hold plan

Try it yourself

Builder header → Pressure advisor. Step 1 prefills TVD + reservoir T from your model. Step 3 shows this exact sum live, with a red chip if it exceeds your pump rating.

Open unified solver with Permian surface-budget inputs

Permian Wolfcamp surface-pressure budget — TVD 9,800 ft, MW 8.5 ppg, 4½-in casing.

Download preset · Permian surface-pressure budget inputs

JSON bundle of every input above (and the expected outputs). Retype the values into Builder header → Pressure advisor to reproduce the calculation step by step.

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?

Input	Value	Source
Parent–child spacing [ft]	660	Plan view, /parent-child
Per-parent drawdown Δp [psi]	1,800	Production timeline (3 yr, τ = 1.5 yr)
Drainage radius r_d [ft]	450	Microseismic P75 fit, or 660/√2
Biot α [-]	0.75	Static model preset
Poisson ν [-]	0.22	Bakken bench
Half-length L [ft]	350	Frac options

Δσ_h ≈ α · (1 - 2ν) / (1 - ν) · Δp = 0.75 · (1 - 0.44) / 0.78 · 1,800 ≈ 970 psi

Eaton/Geertsma poroelastic stress drop in the depleted region. This is what biases the child fracture toward the parent.

Where

α = Biot coefficient
ν = Poisson's ratio
Δp = local drawdown from production timeline

Units: psi

asymmetry = (L_a - L_b) / (L_a + L_b) where L tilts toward the lower-σh side

The probe-point validator computes σh on both sides of each child stage and reports asymmetry %. >25% is the bashing-risk threshold.

Where

L_a = half-length toward depleted parent
L_b = away

Output	Value	Interpretation
Worst-stage Δσ_h [psi]	≈ 970	Watch band — significant rotation
Worst-stage asymmetry [%]	31	Critical — bias toward parent
SHmax shift [°]	12	Watch band (>5° info, >15° critical)
Frac-hit proppant per parent [lb]	≈ 18,400	Volumetric estimate
Recommended action	Re-pressurize parents OR widen spacing 660 → 880 ft	Summary chip

Step-by-step walkthrough — Parent-child screening

1Seed the layout from a regional preset
UI: /parent-child → Inputs aside → 'Bakken-Middle' preset button
Loads spacing, ν, α, drainage radius, and τ for the bench in one click. Override any field you have local data for.
Result: 2 parents at ±330 ft, child at y=0 · ν 0.22 · α 0.75
2Time-resolve drawdown via the production timeline
UI: Per-parent productionStartIso + ultimateDrawdown + τ_years + child pumpDate
Δp_∞ is the ultimate drawdown; τ governs how fast pressure draws down. The child sees Δp at its pump date, not the asymptote.
Δp(t) = Δp_∞ · (1 − exp(−Δt/τ))
Result: After 3 yr at τ = 1.5 yr ⇒ Δp ≈ 1,800 × (1 − e^-2) ≈ 1,556 psi per parent
3Compute the poroelastic σh drop
UI: Far-field stress (full tensor) → toggle on
Eaton/Geertsma drop. With ν = 0.22, the coupling factor is 0.75 × 0.56 / 0.78 ≈ 0.54. Multiply by per-stage Δp from step 2.
Δσ_h ≈ α · (1 − 2ν) / (1 − ν) · Δp
Result: Worst-stage Δσ_h ≈ 970 psi (at the stage closest to both parents)
4Read asymmetry from the probe-point validator
UI: Plan view → click any (x,y) to drop a probe pin
L_a tilts toward the lower-σh side. > 25% triggers the bashing-risk chip.
asymmetry = (L_a − L_b) / (L_a + L_b)
Result: Worst-stage asymmetry = 31% ⇒ Critical (bashing risk)
5Read frac-hit volumetrics + recommended action
UI: Summary chips on the inputs aside
Volumetric estimate uses swept-ellipse capture × depletion-attraction. The summary chip recommends re-pressurize or widen spacing.
Result: ≈ 18,400 lb proppant per parent · Recommended: widen 660 → 880 ft OR re-pressurize

Try it yourself

Open the workspace → /parent-child. Click the 'Bakken-Middle' regional preset to seed spacing/drawdown/τ, then toggle 'Far-field stress (full tensor)' on. The plan view shows rotated SHmax ticks per stage and the table reports asymmetry % live.

Download preset · Parent-child 660 ft Bakken infill inputs

JSON bundle of every input above (and the expected outputs). Retype the values into /parent-child (Bakken-Middle preset) to reproduce the calculation step by step.

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?

Live signal	Value (rolling 60-s window)
Actual peak BHP [psi]	9,420
Planned BHP at same t [psi]	8,930
ΔP residual [psi]	+490
Pnet slope on log-log [-]	+0.25 (Mode III)
Proppant runway at current burn [min]	12.4
Wellbore displacement: first sand at perfs in [min]	1.8

Mode III slope ≈ +0.25 on log(Pnet) vs log(t) ⇒ restricted height growth + tip screen-out forming

Nolte–Smith modes: I flat (radial), II negative (height), III positive shallow (tip-screenout precursor), IV steep positive (true screen-out).

Where

Slope from rolling-window log-log fit on the live BHP - SH_min trace

screen_out_risk = w₁ · z(ΔP) + w₂ · z(slope) + w₃ · 1{runway < 5 min}

Composite risk pill on the LivePumpingPanel. Above 0.7 ⇒ red 'Cut sand now' chip.

Where

w₁,w₂,w₃ = 0.4 / 0.4 / 0.2 default weights
z = z-score over rolling window

Output	Value	Operator action surfaced by the app
Risk pill	0.78 (Red)	Cut sand to 0.5 ppa, hold rate
Auto-history-match knob diff	Γ₂ +14%, K_leak -22%	Suggests tip-restriction, not leak-off
ISIP auto-pick [psi]	8,460 (high confidence)	Logged to Nolte-Smith preset for next stage
Plan vs. actual divergence chip	+490 psi	Visible 90 s before any pump-rating alarm

Step-by-step walkthrough — Live screen-out detection

1Mount the live transport
UI: /live-pumping → transport picker → 'Synthetic stream' (or WS/REST/WITSML)
Pick the source feeding (t, BHP, surface rate, proppant conc) into the rolling buffer. Synthetic stream is the safest sandbox.
Result: Plan curve drawn live in LivePumpingPanel
2Watch the plan-vs-actual residual
UI: PlanDeltaChartPanel → top chip
Computed every sample. Anything sustained > 250 psi is a flag; > 500 psi joins the composite risk score.
ΔP_residual = BHP_actual − BHP_planned
Result: ΔP residual = +490 psi (rising)
3Read the Nolte–Smith mode chip
UI: NolteSmithPanel → mode chip
Mode III is the tip-screenout precursor. Mode IV means it has already started.
slope = d log(Pnet) / d log(t) ⇒ Mode I (≈0) · II (<0) · III (+0.1–0.3) · IV (>0.5)
Result: Slope = +0.25 ⇒ Mode III (tip-screenout forming)
4Check the proppant runway
UI: ProppantInventoryCard → runway chip
If runway < 5 min the composite risk picks up an extra +0.2.
burn = ppa · bpm · 42 (lb/min) · runway = inventory / burn
Result: Runway = 12.4 min · OK band, but watch first-sand-at-perfs (1.8 min)
5Read the composite risk pill + take action
UI: LivePumpingPanel → risk pill (top right)
Above 0.7 the chip turns red and the panel suggests 'Cut sand to 0.5 ppa, hold rate'. The Γ₂ tip knob auto-bumps in NetPressureMatch.
risk = 0.4·z(ΔP) + 0.4·z(slope) + 0.2·1{runway<5}
Result: Risk = 0.78 (Red) ~90 s before any pump-rating alarm fires

Try it yourself

Go to /live-pumping. Pick the 'Synthetic stream' transport and load the 'screen-out demo' job. The risk pill turns red ~90 s before the planned BHP would have reached the 10,000-psi rating, and the Net-pressure match panel suggests the Γ₂ tip knob automatically.

Open Live pumping with synthetic screen-out stream

Live screen-out demo — synthetic stream, 80 bpm, 100-mesh + 40/70.

Download preset · Live screen-out detection inputs

JSON bundle of every input above (and the expected outputs). Retype the values into /live-pumping (Synthetic stream) to reproduce the calculation step by step.

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.

Input	Value	Source
# focal mechanisms (strike, dip, rake)	14	Microseismic vendor catalog (.csv)
Borehole-breakout azimuths (cross-check) [°]	[42, 48, 39, 45]	Image-log interpretation
Regional prior SHmax azimuth [°]	≈ 45 (NE–SW)	World Stress Map · Eagle Ford trend
Min mechanisms required by inverter	≥ 4	invertStressTensor() guard

min Σᵢ |angular_misfit(slip_i, τ_i(σ̂))| over (φ_SHmax, R)

Grid-search inversion: pick the (SHmax azimuth, stress ratio) whose predicted shear traction τᵢ on each fault plane best aligns with the observed slip vector. Mean angular misfit is the objective.

Where

φ_SHmax — SHmax azimuth [°], 0 = North, swept on a 1° grid
R = (S2 − S3) / (S1 − S3) — stress ratio [-], swept on a 0.05 grid
slip_i — observed unit slip vector for mechanism i
τ_i(σ̂) — shear traction predicted by the trial stress tensor on plane i

Driven by (UI fields)

invertStressTensor() in src/lib/geomechanicsStressInversion.ts

SHmax_breakouts = circular_mean(azimuthsᵢ) + 90°

Cross-check: borehole breakouts elongate along SH_min, so SHmax is 90° away. Circular mean handles the 0/180° wraparound cleanly.

Where

shmaxFromBreakouts(azimuthsDeg) returns the SHmax direction in degrees

Output	Value	Where it lands in the app
Inverted SHmax azimuth [°]	47 ± 3	/parent-child far-field card → SHmax azimuth field
Stress ratio R [-]	0.62	Drives σ2 reconstruction in poroelastic engine
Mean angular misfit [°]	11.4	< 15° ⇒ confident inversion
Breakout cross-check SHmax [°]	133.5 + 90 = 43.5	Within 4° of inversion ✓

Step-by-step walkthrough — Stress inversion

1Collect focal mechanisms (strike, dip, rake)
UI: Microseismic vendor delivery → CSV with columns strike,dip,rake
Each event needs all three angles. Reject events with magnitude below your detection threshold or location uncertainty > 50 ft.
Result: 14 mechanisms, all M_w ≥ 0.8
2Run the grid-search inversion
UI: invertStressTensor(mechanisms) → { shmaxAzimuthDeg, stressRatio, meanMisfitDeg }
1° azimuth × 0.05 R grid by default. Function returns the best (φ, R) plus mean angular misfit (a quality metric — < 15° is confident, > 25° suggests heterogeneous stress or noisy mechanisms).
min Σ |angular_misfit| over (φ_SHmax ∈ [0°, 180°), R ∈ [0, 1])
Result: SHmax = 47°, R = 0.62, misfit = 11.4°
3Cross-check with borehole breakouts
UI: shmaxFromBreakouts([42, 48, 39, 45]) → 133.5° (≡ 43.5° SHmax)
Independent measurement from image logs. Agreement within ±10° validates the focal-mechanism inversion; > 20° disagreement means one of the two datasets is wrong.
SHmax_breakouts = circular_mean(azimuths) + 90°
Result: Breakouts give 43.5°, inversion gives 47° ⇒ agree within 4° ✓
4Push the result into the parent–child engine
UI: /parent-child → Far-field stress (full tensor) → SHmax azimuth = 47°
Per-stage SHmax rotation now uses the inverted value instead of the regional prior. Child fracture geometry (β, tip Δ) recomputes automatically.
Result: Stage-by-stage σh rotation reflects field-measured stress

Try it yourself

Open the dev console on /parent-child and run: import('@/lib/geomechanicsStressInversion').then(m => console.log(m.invertStressTensor([{strikeDeg:30,dipDeg:75,rakeDeg:-10},{strikeDeg:210,dipDeg:80,rakeDeg:-15}, ...]))). The returned shmaxAzimuthDeg goes straight into the Far-field card.

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?

Input	Value	Source
Matrix permeability k_m [m²]	1.0 × 10⁻¹⁹ (≈ 0.0001 mD)	Static model · core data
Fracture permeability k_f [m²]	5.0 × 10⁻¹⁴ (≈ 50,000 mD)	Conductivity test
Contact area A [m²]	100	Frac geometry × stage spacing
Half-distance L [m]	0.5	Half cell width
Fracture spacing [m]	1.0	DFN realization
Wellbore radius r_w [m]	0.108 (4½-in)	Casing program
Initial p_matrix / p_frac [Pa]	30 MPa / 25 MPa	Pre-shut-in snapshot
Total compressibility c_t [1/Pa]	1.0 × 10⁻⁹	PVT lumping

CI = k_eff · A / L where k_eff = harmonic_mean(k_m, k_f)

Connectivity index between matrix and embedded fracture (Hajibeygi-style). Harmonic mean dominates by the smaller permeability — so the matrix sets the bottleneck.

Where

k_eff — effective interface permeability [m²]
A — contact area between matrix and fracture [m²]
L — half-distance from matrix center to fracture face [m]

Driven by (UI fields)

matrixFractureCI({ matrixPermM2, fractureK, contactAreaM2, halfDistanceM })

Units: m³ (CI carries dimensions of k·A/L)

λ = (k_m / k_f) · (r_w / s_f)² ω = (φ·c_t)_f / [(φ·c_t)_m + (φ·c_t)_f]

Warren–Root dual-porosity dimensionless groups. λ is the interporosity flow coefficient (how fast matrix recharges fracture); ω is the storativity ratio (how much pressure support comes from the fracture vs the matrix).

Where

s_f — fracture spacing [m]
r_w — wellbore radius [m]
φ_m, φ_f — matrix / fracture porosity [-]
c_t — total compressibility [1/Pa]

Δp_m^{n+1} = Δp_m^n − (CI / V_m c_t) · (p_m − p_f) · Δt

One explicit-Euler step of the matrix–fracture pressure transfer. The driving force is the pressure difference; the time constant is V_m c_t / CI.

Where

V_m — matrix block volume [m³]
Δt — explicit step size, must satisfy CFL on the transfer term

Driven by (UI fields)

stepDualPorosity({ pMatrix, pFracture, ci, volumeM3, ct, dtSec })

Output	Value	Interpretation
k_eff (harmonic mean) [m²]	≈ 2.0 × 10⁻¹⁹	Dominated by matrix — bottleneck is correct
CI [m³]	≈ 4.0 × 10⁻¹⁷	k_eff · A / L = 2e-19 · 100 / 0.5
λ [-]	≈ 2.3 × 10⁻⁸	Tight matrix → very slow recharge (Warren–Root weak coupling)
ω [-]	≈ 0.15	Fracture stores ≈ 15% of total pore volume
Δp after 1 hr shut-in [Pa]	p_m drops < 1 kPa	Matrix barely moves — fracture pressure dominates
τ_transfer = V_m c_t / CI [s]	≈ 2.5 × 10⁵ (≈ 70 hr)	1 hr ≪ τ ⇒ explicit step OK at any reasonable dt

Step-by-step walkthrough — Embedded DFN transfer

1Compute the connectivity index
UI: matrixFractureCI({ matrixPermM2: 1e-19, fractureK: 5e-14, contactAreaM2: 100, halfDistanceM: 0.5 })
The harmonic mean of two permeabilities differing by 5 orders of magnitude is ≈ 2× the smaller one — so the matrix sets the bottleneck. CI carries units of m³ because it absorbs the 1/μ that lives in the Darcy step.
CI = harmonic_mean(k_m, k_f) · A / L
Result: CI ≈ 4.0 × 10⁻¹⁷ m³
2Compute Warren–Root λ and ω
UI: warrenRootLambda(k_m, k_f, s_f, r_w) · warrenRootOmega(φ_m, c_tm, φ_f, c_tf)
λ ≪ 10⁻⁵ means the matrix is essentially decoupled on field time scales — production comes off the fracture, then very slowly off the matrix. ω near 0.1 means the fracture system stores 10–20% of the recoverable pore volume.
λ = (k_m / k_f) · (r_w / s_f)² ω = (φc_t)_f / [(φc_t)_m + (φc_t)_f]
Result: λ ≈ 2.3 × 10⁻⁸ · ω ≈ 0.15
3Step the dual-porosity transfer
UI: Loop stepDualPorosity({...}) for N steps of dt = 60 s over 1 hr
Explicit Euler. Stable as long as Δt ≤ 2 V_m c_t / CI (≈ 5 × 10⁵ s here, so 60-s steps are massively safe). Each step bleeds a little matrix pressure into the fracture.
Δp_m^{n+1} = Δp_m^n − (CI / V_m c_t) · (p_m − p_f) · Δt
Result: After 1 hr, p_m drops < 1 kPa from 30 MPa → matrix is essentially static
4Decide if you need EDFM at all
UI: Compare τ_transfer to your simulation horizon
If τ_transfer ≫ horizon (here 70 hr ≫ 1 hr), single-porosity with effective fracture permeability is accurate enough — the matrix contributes nothing. EDFM pays off when τ_transfer is within 10× of the horizon (typically multi-week / multi-month forecasts).
Result: 1 hr shut-in: skip EDFM. 6-month forecast: enable it.

Try it yourself

All three helpers (matrixFractureCI, warrenRootLambda, warrenRootOmega, stepDualPorosity) live in src/lib/embeddedDfnConductivity.ts and are pure SI. Punch the inputs into a console, or wire them into a small ResultsObservationsCard for a dual-porosity workspace.

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?

Input	Value	Source
Particle diameter d_p [m]	1.50 × 10⁻⁴ (100-mesh)	Proppant catalog
Particle density ρ_s [kg/m³]	2,650 (silica)	Proppant catalog
Fluid viscosity μ [Pa·s]	0.003 (3 cP, slickwater + FR)	Rheology preview
Fluid density ρ_f [kg/m³]	1,005 (FR-treated water)	Carrier fluid
Slurry concentration [ppa → vol frac]	0.5 ppa ⇒ φ ≈ 0.022	Treatment schedule
Fracture length / height [m]	200 / 30	Frac geometry
Pump time [s]	1,800 (30 min)	Treatment schedule
Net pump rate per fracture [m³/s]	0.05	Stage rate / # clusters

v_Stokes = g · (ρ_s − ρ_f) · d_p² / (18 · μ)

Stokes settling velocity for a single particle in laminar flow (Re_p < 1). Always the FIRST thing you compute — it tells you whether settling matters in the first place.

Where

g = 9.81 m/s²
ρ_s, ρ_f — particle and fluid density [kg/m³]
d_p — particle diameter [m]
μ — fluid viscosity [Pa·s]

Driven by (UI fields)

stokesSettlingVelocity(particle, fluid)

Units: m/s

Re_p = ρ_f · v · d_p / μ then v_terminal = either Stokes (Re_p < 1) or Newton drag (Re_p > 1000)

If the Stokes Reynolds number is > 1, you must switch to Newton drag (turbulent terminal velocity) — for big proppant (40/70, 30/50) in slickwater this is almost always required.

Where

Re_p — particle Reynolds number [-]

Driven by (UI fields)

terminalSettlingVelocity(particle, fluid) auto-picks the regime

v_hindered = v_terminal · (1 − φ)^n Richardson–Zaki, n ≈ 4.65 (laminar)

Particle–particle interactions slow settling at higher concentrations. At φ = 0.02 the correction is ≈ 9% (small); at φ = 0.20 it is ≈ 60%.

Where

φ — local volume fraction of solids [-]
n — Richardson–Zaki exponent (≈ 4.65 in Stokes regime, ≈ 2.4 in Newton)

Driven by (UI fields)

hinderedSettling(vTerminal, volumeFraction, n?)

h_bank = min(h_frac, v_hindered · t_pump · (φ_in / φ_pack) · L_frac / Q_horizontal)

Equilibrium bank height: the volume of proppant that settles inside the pump window, reorganized at packed concentration (φ_pack ≈ 0.55–0.62), divided by the fracture footprint area being swept.

Where

h_frac — fracture height [m] (caps the bank)
t_pump — pump duration [s]
φ_in, φ_pack — slurry and packed-bed volume fractions [-]
L_frac, Q_horizontal — geometry and net horizontal carry rate

Driven by (UI fields)

predictBankHeight({ velocity, time, fractureHeightM, fractureLengthM, slurryFraction, packedFraction })

Units: m (bank height) and [-] (coverage = h_bank / h_frac)

Output	Value	Interpretation
v_Stokes [m/s]	≈ 0.020 (1.2 m/min)	100-mesh in 3 cP slickwater settles fast
Re_p [-]	≈ 1.0	Borderline — Stokes still ≈ correct, but a 40/70 sand at the same conditions would need Newton drag
v_hindered at φ = 0.022 [m/s]	≈ 0.018	9% slowdown vs single-particle Stokes
Bank height h_bank [m]	≈ 7.4	≈ 25% of the 30-m fracture height settles out
Coverage fraction (h_bank / h_frac) [-]	0.25	75% of the upper fracture is unpropped — classic slickwater concern
Recommended action	Bump rate (cuts settling time) OR increase ppa OR slugify	Lift coverage above 0.5

Step-by-step walkthrough — Bank height prediction

1Compute Stokes velocity FIRST
UI: stokesSettlingVelocity({ diameterM: 150e-6, densityKgM3: 2650 }, { viscosityPaS: 0.003, densityKgM3: 1005 })
For 100-mesh sand in slickwater you get ≈ 2 cm/s. That's a meaningful 1.2 m/min — proppant will land long before pump-off.
v_Stokes = g · (ρ_s − ρ_f) · d_p² / (18 μ)
Result: v_Stokes ≈ 0.020 m/s
2Check the particle Reynolds number
UI: Re_p = 1005 · 0.020 · 1.5e-4 / 0.003 ≈ 1.0
Stokes is valid for Re_p < 1. At Re_p ≈ 1 you're at the boundary — terminalSettlingVelocity() auto-switches to Newton drag (≈ 2× higher v) for bigger sand.
Re_p = ρ_f · v · d_p / μ
Result: Re_p ≈ 1.0 → Stokes still applies for 100-mesh; auto-switch trips at 40/70
3Apply hindered settling at slurry concentration
UI: hinderedSettling(0.020, 0.022, 4.65)
0.5 ppa is φ ≈ 0.022. The Richardson–Zaki correction trims velocity by 9%. At 4 ppa (φ ≈ 0.18) you'd lose nearly 60%.
v_hindered = v · (1 − φ)^n n ≈ 4.65
Result: v_hindered ≈ 0.018 m/s
4Predict bank height
UI: predictBankHeight({ velocity: 0.018, time: 1800, fractureHeightM: 30, fractureLengthM: 200, slurryFraction: 0.022, packedFraction: 0.55 })
Bank caps at fracture height. Coverage fraction = h_bank / h_frac is the sand-coverage you'll get on the propped surface.
h_bank = min(h_frac, v · t_pump · (φ_in / φ_pack) · L / Q_horiz)
Result: h_bank ≈ 7.4 m · coverage ≈ 25%
5Decide what to change
UI: Compare coverage to your design target (typically ≥ 0.5)
Coverage 25% is the well-known slickwater problem. Three levers: (1) lift carrier viscosity (linear gel cuts v_Stokes by μ), (2) lift rate (cuts residence time), or (3) slugify (concentrate proppant in short bursts). Most operators run all three.
Result: Plan B: 5 cP linear gel + 1 ppa slugs ⇒ recompute, expect coverage ≈ 0.55

Try it yourself

All four helpers (stokesSettlingVelocity, terminalSettlingVelocity, hinderedSettling, predictBankHeight) live in src/lib/proppantSettlingPlacement.ts. Drop them into a small panel under Builder → Proppants to show coverage % live as the engineer slides ppa or rate.

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?

Input	Value	Source
Cumulative injected volume [bbl]	1,500,000 (50k bbl/d × 30 d)	Operator schedule
Shear modulus G [Pa]	2.0 × 10¹⁰ (typical basement)	Static model · core / sonic
Optional fault patch area [m²]	1.0 × 10⁶ (1 km × 1 km)	Mapped fault from 3D seismic
Optional average slip D [m]	0.05 (assumed scenario)	Stress-drop scenario
Severity ladder	Mw < 2 info · < 3 watch · < 4 amber · ≥ 4 critical	screenInducedSeismicity()

M0_max = G · ΔV_injected (McGarr 2014)

Volumetric upper bound on the seismic moment any single induced event could release — assumes ALL injected volume drives slip on a single fault patch (worst case).

Where

G — shear modulus of host rock [Pa]
ΔV — cumulative net injected volume [m³]
M0_max — maximum seismic moment [N·m]

Driven by (UI fields)

mcGarrMaxMoment(deltaVolumeM3, shearModulusPa)

Mw = (2/3) · (log₁₀(M0) − 9.1) (Kanamori 1977)

Convert seismic moment to moment magnitude. Each unit of Mw corresponds to ~32× more energy.

Where

M0 — seismic moment [N·m]
Mw — moment magnitude [-]

Driven by (UI fields)

momentMagnitudeFromM0(m0NewtonM)

M0_det = G · A · D (deterministic scenario, optional)

If a specific fault patch + average slip are known, compute a deterministic Mw. Compare against the McGarr upper bound — they should bracket the realistic answer.

Where

A — fault patch area [m²]
D — average slip on the patch [m]

Driven by (UI fields)

seismicMomentFromSlip({ areaM2, shearModulusPa }, slipM)

Output	Value	Interpretation
Injected volume ΔV [m³]	≈ 2.385 × 10⁵ (1.5 M bbl × 0.159)	BBL_TO_M3 = 0.158987
McGarr M0_max [N·m]	≈ 4.77 × 10¹⁵	G · ΔV
McGarr Mw upper bound [-]	≈ 4.4	(2/3)·(log₁₀(4.77e15) − 9.1)
Severity band	critical (≥ 4)	Triggers traffic-light protocol review
Deterministic Mw (1 km² × 0.05 m slip)	≈ 4.6	G·A·D ⇒ M0 = 1e15 N·m ⇒ Mw 4.6
Recommended action	Stagger injection · monitor · cap daily volume	Bring Mw_upper below 4

Step-by-step walkthrough — Induced-seismicity screen

1Convert injected barrels to m³
UI: BBL_TO_M3 constant in src/lib/inducedSeismicityScreen.ts
1,500,000 bbl × 0.158987 ≈ 238,481 m³.
ΔV [m³] = bbl × 0.158987
Result: ΔV ≈ 2.385 × 10⁵ m³
2Apply the McGarr volumetric bound
UI: mcGarrMaxMoment(238481, 2e10)
Treats the entire injected volume as the elastic strain energy reservoir for slip. This is conservative — most operators use it as a screening tool, not a forecast.
M0_max = G · ΔV
Result: M0_max ≈ 4.77 × 10¹⁵ N·m
3Convert to moment magnitude
UI: momentMagnitudeFromM0(4.77e15)
Kanamori (1977). The −9.1 constant assumes M0 in N·m (use −16.1 for dyn·cm).
Mw = (2/3) · (log₁₀(M0) − 9.1)
Result: Mw ≈ 4.4
4Read the severity chip + decide next step
UI: screenInducedSeismicity({ injectedBarrels, shearModulusPa, ... }) → severity
info < 2, watch < 3, amber < 4, critical ≥ 4. A 'critical' chip means the operator should engage their traffic-light protocol (TLP), throttle injection, and review monitoring density.
Result: Severity = critical · TLP review required

Run Example 8 — Induced-seismicity Mmax

Live calculator · Induced-seismicity Mmax

Preset

Inputs

Injected volume[bbl]Shear modulus G[GPa]Fault patch area (opt)[km²]Avg slip (opt)[m]

Outputs (live)

ΔV

2e+5m³

M0_max (McGarr)

4.77e+15N·m

Mw upper boundinfo <2 · watch <3 · amber <4 · critical ≥4

4.39

critical

Mw deterministic (G·A·D)From fault patch + slip

3.93

Try it yourself

All helpers (mcGarrMaxMoment, momentMagnitudeFromM0, seismicMomentFromSlip, screenInducedSeismicity, BBL_TO_M3) live in src/lib/inducedSeismicityScreen.ts. Wire them into a small SWD-volume slider on /parent-child to show Mw_upper live as the operator drags daily injection.

Open unified solver with SWD seismicity inputs

SWD induced-seismicity screen — 50,000 bbl/day × 30 days, μ = 30 GPa.

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)?

Input	Value	Source
Oil API gravity [°API]	35	Sales-line gravity test
Gas specific gravity γg [-]	0.75 (separator gas)	Gas chromatograph
BHST [°F]	240	Builder → Fluid model
Bubble-point pressure pb [psia]	2,500	PVT lab (CCE)
Flowing BHP, case A [psia]	4,000 (undersaturated)	Well controls
Flowing BHP, case B [psia]	1,800 (saturated)	Well controls

Rs(p) = γg · [(p / 18.2 + 1.4) · 10^(−a)]^(1/0.83), a = 0.00091·T − 0.0125·API

Standing (1947) solution gas-oil ratio. Used for p ≤ pb; clamped at Rs(pb) for undersaturated oil.

Where

p — pressure [psia]
T — temperature [°F]
Rs — solution GOR [scf/STB]

Driven by (UI fields)

standingRs(p, t, api, γg)

Bo_sat = 0.9759 + 0.00012 · [Rs · √(γg / γo) + 1.25·T]^1.2, γo = 141.5 / (API + 131.5)

Standing oil formation-volume factor at saturated conditions [bbl/STB]. γo is oil specific gravity from API.

Where

Bo_sat — saturated FVF [bbl/STB]
γo — oil specific gravity [-]

Driven by (UI fields)

standingBoSaturated(rs, t, api, γg)

co = (−1433 + 5·Rs + 17.2·T − 1180·γg + 12.61·API) / (1e5 · p)

Vasquez-Beggs oil isothermal compressibility [1/psi] above bubble point — drives Bo decompression and material-balance.

Where

co — oil compressibility [1/psi]

Driven by (UI fields)

vasquezBeggsCo(rs, t, api, γg, p)

Bo(p > pb) = Bob · exp[−co · (p − pb)]

Above bubble point, Bo shrinks with pressure following oil compressibility. At p ≤ pb, Bo = Bo_sat(Rs(p)).

Where

Bob — Bo at bubble point [bbl/STB]

Driven by (UI fields)

boUndersaturated(bob, co, p, pb)

Output	Case A · p = 4,000 psia	Case B · p = 1,800 psia	Interpretation
Saturated? [-]	false (undersaturated)	true (saturated)	p vs pb
Rs [scf/STB]	≈ 597 (clamped at Rs(pb))	≈ 386 (Standing at p)	Free gas comes out below pb
Bo [bbl/STB]	≈ 1.296 (Bob · exp[−co·Δp])	≈ 1.236	Oil expands as gas evolves
co [1/psi]	≈ 1.4 × 10⁻⁵	≈ 1.5 × 10⁻⁵	Vasquez-Beggs
γo [-]	0.850	0.850	141.5 / (35 + 131.5)

Step-by-step walkthrough — Black-oil PVT snapshot

1Decide saturated vs undersaturated
UI: blackOilProperties({ pressurePsi: p, bubblePointPsi: pb, ... })
Above pb the oil is single-phase liquid; below pb free gas evolves and Rs starts dropping.
isSaturated = (p ≤ pb)
Result: Case A: p = 4,000 > pb = 2,500 ⇒ undersaturated. Case B: saturated.
2Compute Rs (clamped at pb for undersaturated)
UI: standingRs(p_eff, 240, 35, 0.75)
Standing's correlation. For undersaturated oil, Rs is fixed at Rs(pb) — no more gas can come out of solution.
Rs = standingRs(min(p, pb), T, API, γg)
Result: Case A: Rs ≈ 597 scf/STB · Case B: Rs ≈ 386 scf/STB
3Compute Bo at bubble point, then adjust
UI: standingBoSaturated(...) · boUndersaturated(...)
Bo peaks near bubble point. Above pb it decreases with pressure (oil compresses); below pb it decreases with pressure (less gas in solution).
Bob = standingBoSaturated(Rs(pb), …) then Bo = isSaturated ? Bob(Rs(p)) : Bob · exp[−co·(p−pb)]
Result: Case A: Bo ≈ 1.296 bbl/STB · Case B: Bo ≈ 1.236 bbl/STB
4Push Rs/Bo/co into the material-balance + IPR
UI: Builder → Fluid model · Results → IPR card
Bo and co set the material-balance drive index; Rs sets the GOR forecast. A 5% Bo error propagates ~5% to STB recovery — get this right.
Result: PVT snapshot used by /economics DCA tab + Vogel IPR

Run Example 9 — Black-oil PVT snapshot

Live calculator · Black-oil PVT (Standing / Vasquez-Beggs)

Preset

Inputs

Pressure p[psia]Bubble point pb[psia]Temperature[°F]Oil API[°API]Gas gravity γg

Outputs (live)

State

Undersaturated

info

525scf/STB

1.3134bbl/STB

1.22e-51/psi

γo141.5 / (API + 131.5)

0.85

Try it yourself

All five helpers (standingBubblePoint, standingRs, standingBoSaturated, vasquezBeggsCo, boUndersaturated) plus the wrapper blackOilProperties live in src/lib/blackOilCorrelations.ts. Use blackOilProperties({…}) to get a one-line snapshot for any (p, T, pb, API, γg) combination.

Open unified solver with Bakken black-oil PVT inputs

Bakken black-oil PVT — 35°API, γg 0.75, pb 2,500 psia, BHST 240 °F.

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?

Input	Value	Source
Outer diameter OD [in]	5.500	Casing tally
Wall thickness t [in]	0.304 (nominal P-110 17 lb/ft)	API spec
Yield strength Yp [psi]	110,000 (P-110 grade)	Mill cert
Collapse load [psi]	6,200 (full evacuation @ 9,500 ft)	Worst-case collapse scenario
Burst load [psi]	9,800 (frac BHP − backside)	Treatment design
Axial load [lbf]	350,000 (hanging weight + drag)	Tubular drag model
Design factors (burst / collapse / axial)	1.10 / 1.125 / 1.6	Operator standard (API 5C3 default)

P_burst = 2 · Yp · t / OD (Barlow)

Internal-pressure rating from Barlow's thin-wall hoop-stress formula. Conservative for oilfield D/t.

Where

Yp — yield strength [psi]
t — wall thickness [in]
OD — outer diameter [in]

Driven by (UI fields)

barlowBurstPsi(spec)

Units: psi

P_collapse_yield = 2·Yp · (D/t − 1) / (D/t)² API yield-strength regime

Low-D/t collapse pressure. Beyond a critical D/t the rating switches to the plastic regime (API 5C3 Pe = Yp·(A/D-t − B) − C).

Where

D/t — diameter-to-thickness ratio [-]

Driven by (UI fields)

yieldCollapsePsi(spec) · plasticCollapsePsi(spec) · collapseRatingPsi(spec) auto-picks the max

F_axial = Yp · A_pipe A_pipe = (π/4) · (OD² − ID²)

Axial yield load [lbf] = yield strength × pipe cross-sectional area of steel.

Where

A_pipe — steel cross-section [in²]
ID = OD − 2·t — inner diameter [in]

Driven by (UI fields)

axialYieldLbf(spec)

SF_x = Rating_x / Load_x passes ⇔ SF_burst ≥ DF_b ∧ SF_collapse ≥ DF_c ∧ SF_axial ≥ DF_a

API 5C3 design check: each loading mode must clear its design factor. Failing any one ⇒ string fails.

Where

DF — design factor (operator standard, typically 1.10 / 1.125 / 1.6)

Driven by (UI fields)

checkCasingDesign(spec, loads, designFactors)

Output	Value	Interpretation
D/t [-]	≈ 18.1	5.5 / 0.304
Burst rating P_burst [psi]	≈ 12,160	2 · 110,000 · 0.304 / 5.5
Collapse rating [psi]	≈ 11,080 (yield regime dominates)	API 5C3 max(yield, plastic)
Axial yield [lbf]	≈ 565,400	110,000 × A_pipe (A_pipe ≈ 5.14 in²)
Burst SF	≈ 1.24 (≥ 1.10) ✓	12,160 / 9,800
Collapse SF	≈ 1.79 (≥ 1.125) ✓	11,080 / 6,200
Axial SF	≈ 1.62 (≥ 1.6) ✓ (just passes)	Watch — bump grade or wall if drag rises
Design verdict	PASS	All three SF clear their design factors

Step-by-step walkthrough — Casing design check

1Build the spec + loads
UI: spec = { odIn: 5.5, wallIn: 0.304, yieldPsi: 110000 }; loads = { burstLoadPsi: 9800, collapseLoadPsi: 6200, axialLoadLbf: 350000 }
Use mill-certified yield (nominal grade × min spec). Loads come from the worst-case operating envelope (full evacuation for collapse, frac BHP for burst, total hung weight + drag for axial).
Result: Spec + 3 loads ready for the checker
2Compute ratings
UI: barlowBurstPsi · collapseRatingPsi · axialYieldLbf
Barlow for burst; API 5C3 with the larger of yield-strength and plastic regimes for collapse; A_pipe × Yp for axial.
P_burst = 2·Yp·t/OD · P_collapse = max(yield, plastic) · F_axial = Yp·A_pipe
Result: Burst 12,160 psi · Collapse 11,080 psi · Axial 565,400 lbf
3Divide by loads → SFs
UI: checkCasingDesign(spec, loads, { burst: 1.10, collapse: 1.125, axial: 1.6 })
The check returns burstSafetyFactor, collapseSafetyFactor, axialSafetyFactor, and a single passes boolean.
SF_x = Rating_x / Load_x
Result: Burst 1.24 · Collapse 1.79 · Axial 1.62 · passes = true
4Compare to design factors + decide
UI: Builder → Wells & perforations → Casing program
Fail any one ⇒ upgrade grade (e.g. P-110 → Q-125), thicken wall, or relieve loads (rate down on collapse, lower frac BHP on burst). Here axial is the tightest — if drag estimates change, re-check.
Result: Verdict: PASS, but axial SF is the bottleneck — re-check if BHA / drag changes.

Run Example 10 — Casing burst / collapse / axial check

Live calculator · Casing burst / collapse / axial check

Preset

Inputs

OD[in]Wall t[in]Yield Yp[psi]Burst load[psi]Collapse load[psi]Axial load[lbf]DF burstDF collapseDF axial

Outputs (live)

SF burst (≥ 1.1)

1.24

pass

SF collapse (≥ 1.125)

184.43

pass

SF axial (≥ 1.6)

1.56

fail

Overall verdict

FAIL

fail

Try it yourself

All helpers (diameterToThickness, barlowBurstPsi, yieldCollapsePsi, plasticCollapsePsi, collapseRatingPsi, axialYieldLbf, checkCasingDesign) live in src/lib/casingDesign.ts. Wire checkCasingDesign() into a Builder → Wells & perforations card to chip PASS/FAIL live as the engineer slides BHP / evacuation depth / hung weight.

Open unified solver with Permian P-110 casing inputs

Permian 5½-in 17 lb/ft P-110 casing check — TVD 9,500 ft, internal 9,800 psi.

Why these ten?

Examples 1–4 exercise the four hardest end-to-end workflows (calibration, planning, parent–child screening, real-time detection). Examples 5–7 zoom into three calculation kernels (stress inversion · embedded DFN transfer · proppant bank settling). Examples 8–10 cover three regulatory / hardware-rating screens engineers must clear before any treatment: induced-seismicity Mmax, black-oil PVT, and casing collapse/burst. Reproduce all ten and you understand both the workflows and the math.

6. Physics & equations (what runs in the background)

Every formula behind the inputs you change in sensitivity studies — fracture toughness, leak-off, hydrostatic, breakdown, stress shadowing, and proppant transport.

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)#

P_breakdown = 3·SH_min - SH_max + T₀ - P_pore

Pressure required to initiate a vertical fracture in the wellbore (full-tensor Hubbert-Willis criterion).

Used in

Pressure Advisor — Step 4 (Breakdown) when SH_max anisotropy is known

Calibration hub — Kirsch-stress form for openhole / oriented perforations

Module

src/lib/pressureAdvisor.ts → breakdownPressurePsi (tensor branch)

Where

SH_min — minimum horizontal stress [psi]
SH_max — maximum horizontal stress [psi]
T₀ — tensile strength of the rock [psi]
P_pore — pore pressure [psi]

Driven by (UI fields)

Static model → SH_min, SH_max, P_pore
Calibration → T₀ (fitted from DFIT)

Assumptions

Vertical wellbore, vertical fracture initiation
Linear-elastic isotropic rock at the perf face
No thermal or poroelastic Δσ correction

Validity range

Use whenever SH_max ≠ SH_min (measurable horizontal stress anisotropy).

Units: psi (field) or kPa (SI)

P_breakdown ≈ SH_min + T₀ - P_pore

Uniaxial reduction of the tensor form above, used when SH_max ≈ SH_min (isotropic horizontal stress).

Used in

Section 4 — Pressure advisor walkthrough (Step 4)

Section 5 — Examples 1 & 2 (worked numbers)

Pressure Advisor — Step 4 (Breakdown) default branch

Module

src/lib/pressureAdvisor.ts → breakdownPressurePsi (uniaxial branch)

Where

Identical to the tensor form with SH_max = SH_min ⇒ 3·SH_min − SH_max = 2·SH_min, then a further simplification collapses to SH_min in cased+perforated completions where the cohesion term carries the rest.

Assumptions

SH_max ≈ SH_min (low horizontal-stress anisotropy)
Cased + perforated completion (pre-existing perforation; no rock-cohesion term)
Effective-stress form (P_pore subtracted from total stress)

Validity range

Vertical well, low-anisotropy unconventional plays (Bakken, Eagle Ford, Permian). For high anisotropy switch back to the tensor form above.

Units: psi (field) or kPa (SI)

6.2 Mode-I fracture toughness (propagation criterion)#

K_I = (P_net) · √(π · a) ≥ K_IC

A fracture propagates when the stress-intensity factor K_I exceeds the rock's mode-I fracture toughness K_IC.

Where

K_I — stress-intensity factor at the tip [psi·√in]
P_net = P_frac - SH_min — net pressure inside the fracture [psi]
a — fracture half-length [in]
K_IC — fracture toughness, fitted from DFIT or from lab data [psi·√in]

Driven by (UI fields)

Fracture options → K_IC (this is the parameter you swept in sensitivity)
Static model → SH_min
Well controls → pump rate (drives P_frac)

Units: psi·√in (field) — typical Bakken range 1,000–2,500 psi·√in

Φ(K_IC, C_L) = Σᵢ [ p_obs(tᵢ) − p_model(tᵢ; K_IC, C_L) ]²

Least-squares residual that the DFIT calibration minimises over the post-closure G-function window to back out K_IC (and optionally C_L).

Used in

DFIT calibration — closure-fit minimiser

Calibration report (PDF + CSV) — Inputs · Assumptions · fitted T₀/K_IC section

Module

src/lib/dfit.ts → fitDfitClosure

Where

p_obs(tᵢ) — measured bottomhole pressure at sample i [psi]
p_model(tᵢ; K_IC, C_L) — Carter-II falloff prediction with trial K_IC and Carter coefficient
tᵢ — sample times inside the post-closure G-function window

Assumptions

Least-squares (Gaussian) residual on the post-closure window
Carter-II falloff is the forward operator (1-D leak-off, planar fracture)
Equal weighting per sample; no robust loss

Validity range

Post-closure window only; ≥ 6 samples; K_IC search bounds 0.5–2.5 MPa·√m.

What raising K_IC does in a sensitivity

Higher K_IC → harder for the fracture tip to advance → shorter, fatter fractures at the same pump energy. Net pressure rises and treating pressure rises with it. In Results you'll see longer pump times to hit the same proppant placement.

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

v_L(t) = C_L / √(t - τ)

Carter's 1-D leak-off velocity at a fracture face element first exposed at time τ.

Where

v_L — leak-off velocity normal to the fracture face [ft/min]
C_L — Carter leak-off coefficient [ft/√min]
t — current simulation time [min]
τ — time the element first opened [min]

Driven by (UI fields)

Fracture options → C_L (Carter coefficient — the second-most-common sensitivity parameter)
Curve sets → relative permeability (sets effective C_L through compressibility)

Units: C_L in ft/√min (field) or m/√s (SI)

6.4 Wellbore hydrostatic pressure#

P_hydrostatic = 0.052 · ρ_mud · TVD

Bottomhole pressure contribution from a static column of fluid (field-units form).

Where

P_hydrostatic — pressure at depth [psi]
0.052 — unit conversion (psi · gal) / (lb · ft)
ρ_mud — mud weight [ppg]
TVD — true vertical depth [ft]

Driven by (UI fields)

Pressure advisor → mud weight
Wells & perforations → TVD

Units: psi (P), ppg (ρ), ft (TVD)

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

μ(T) = μ_ref · exp[ E_a / R · (1/T − 1/T_ref) ] (T, T_ref in Kelvin)

Single-step Arrhenius viscosity decay along the fracture as the carrier warms from injection temperature toward bottomhole static temperature (BHST). Composes with first-order breaker decay as μ_eff(x) = μ(T(x)) · (1/2)^(t_res(x)/T½).

Used in

Builder Fluid model → Temperature-dependent μ(x) along fracture card

Proppant concentration map → per-x viscosity feeds Richardson–Zaki settling

Module

src/lib/fluidRheologyTemperature.ts → viscosityProfileAlongFracture

Where

μ(T) — local viscosity at fracture cell temperature T [cP]
μ_ref — bench viscosity at reference temperature (default 150 °F) [cP]
E_a — activation energy (per family; see §11) [kJ/mol]
R — universal gas constant 8.314 [J/(mol·K)]
T, T_ref — temperatures in absolute units [K]

Driven by (UI fields)

Fluid model → fluid family, μ_ref, T limit
Static model → BHST
Well controls → injection T, residence time

Assumptions

Single-step Arrhenius — no shear-history or polymer-degradation coupling
Linear T-ramp from injection to BHST (override-able)
Above the fluid's temperature limit the model still evaluates μ but flags the cell out-of-band rather than zeroing it

Validity range

Slickwater / linear-gel / crosslinked families with bench rheometer data. Activation energies are family-level defaults — override per job with measured fits.

Units: cP (μ), kJ/mol (E_a), K (T)

6.5 PKN fracture width (height-contained model)#

w_max = 2.31 · [ (q · μ · L) / (E' · h) ]^(1/4)

Perkins-Kern-Nordgren maximum fracture width for a height-contained planar fracture.

Where

w_max — peak width at the wellbore [in]
q — slurry rate per fracture [bpm]
μ — apparent fluid viscosity [cP]
L — fracture half-length [ft]
E' = E / (1 - ν²) — plane-strain modulus [psi]
h — fracture height [ft]

Driven by (UI fields)

Static model → Young's modulus E, Poisson's ratio ν
Well controls → pump rate q
Fluid model → viscosity μ

6.6 Proppant transport (settling velocity, Stokes)#

v_s = ( g · d² · (ρ_p - ρ_f) ) / (18 · μ)

Stokes terminal settling velocity for a proppant grain in slurry. Used to predict where proppant lands inside the fracture.

Where

v_s — settling velocity [ft/s]
g — gravitational acceleration [ft/s²]
d — grain diameter [in] (mesh size)
ρ_p — proppant density [lb/ft³]
ρ_f — fluid density [lb/ft³]
μ — slurry viscosity [cP]

Driven by (UI fields)

Proppants → mesh size (sets d), proppant type (sets ρ_p)
Fluid model → ρ_f and μ

6.6b Boycott tilt enhancement#

F_Boycott = 1 + (L · sin θ / w) · F_RZ (capped at 50×)

Multiplier on Stokes settling velocity for a tilted fracture. In a non-vertical fracture, grains slide along the upper face and accelerate the bulk settling rate (the Boycott effect).

Used in

Live Pumping — Proppant dune overlay (severity chip)

Proppant bank-height prediction (Section 5 — Example 7)

Module

src/lib/proppantDuneMechanics.ts

Where

L — fracture characteristic length [ft]
θ — tilt angle from horizontal [rad]
w — fracture width [ft]
F_RZ — Richardson-Zaki hindered-settling factor (1−φ)^n, n ≈ 4.65

Assumptions

Stokes settling regime (Re_p < 1)
Tilt angle θ measured from horizontal (θ = 0 ⇒ vertical fracture, no enhancement)
F_RZ already absorbs concentration-dependent hindering

Validity range

0 ≤ θ ≤ 60°; multiplier hard-capped at 50× to prevent runaway in near-horizontal fractures.

6.7 Stress shadow (Sneddon)#

Δσ_h(r) = P_net · [ 1 - r / √(r² + c²) ]

Increase in horizontal stress at distance r from a planar fracture of half-height c, used to model cluster-to-cluster interference.

Where

Δσ_h — induced stress increase [psi]
P_net — net pressure inside the source fracture [psi]
r — perpendicular distance from the fracture plane [ft]
c — fracture half-height [ft]

Driven by (UI fields)

Wells & perforations → cluster spacing
Fracture options → height growth limits

Trace any number back to its formula

In Results, click the 🔍 icon next to any computed value. The Equation Trace overlay highlights which formula produced it and which input panels feed each variable.

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

σ_θ_dev = σ_θ_v + sin²(inc) · [(1 + cos(2β))/2] · (σ_v − SH_min) ⇒ P_break(inc) = P_break(0) · σ_θ_dev / σ_θ_v

Adjusts the vertical-well Hubbert-Willis breakdown for inclination + azimuth. At inc = 0 the factor is exactly 1.0 (Pressure Advisor's simplified form). For a deviated lateral drilled at angle β to SH_max, the overburden contributes via sin²(inc).

Used in

Pressure Advisor — Step 4 (Breakdown check) when survey inclination ≠ 0

Module

src/lib/wellboreInclinationFactor.ts → wellboreInclinationFactor / adjustBreakdownForInclination

Where

inc — wellbore inclination from vertical [deg]
β — angle between wellbore azimuth and SH_max [deg]
σ_v — overburden stress (defaults to 1.05·SH_max if unknown) [psi]
SH_min, SH_max — horizontal in-situ stresses [psi]
σ_θ_v = 3·SH_min − SH_max − P_pore (classical Hubbert-Willis)

Assumptions

Failure occurs in the SH_min direction around the wellbore wall
Linear elastic rock; no near-wellbore plasticity
σ_v ≈ 1.05·SH_max when overburden gradient unmeasured

Validity range

Inclination clamped to [0°, 90°]; collapses byte-identically to the vertical form at inc = 0 regardless of azimuth. Best for inclinations < 60° drilled in tight unconventional rock; highly deviated wells in plastic shales need a full geomechanical run.

Units: psi

6.8 DFIT K_IC fit objective (Carter II substituted)#

min_{K_IC, C_L} Σᵢ [ P_meas(tᵢ) − P_Carter(tᵢ; K_IC, C_L, SH_min, V_0) ]²

Explicit least-squares cost for the closure-tail fit. The Carter II falloff is substituted directly so the residual chart on the calibration card shows per-sample error contributions.

Used in

DFIT calibration card — K_IC fit + residual chart

Calibration report PDF (T₀, K_IC, C_L block)

Module

src/lib/fractureValidation.ts → fitCarterFalloff

Where

P_meas(tᵢ) — measured BHP at sample i [psi]
P_Carter(t; K_IC, C_L, …) — analytical falloff model
K_IC — fracture toughness [psi·√in]
C_L — Carter leak-off coefficient [ft/√min]
V_0 — closure-time fracture volume [ft³]

Assumptions

Single-fracture geometry assumption holds through shut-in
Pressure-dependent leak-off not active before closure
ISIP and SH_min already picked / known

Validity range

Falloff window from ~3·G to closure for tight reservoirs; gel-coated proppant cases need a damage multiplier on C_L.

Units: psi (residuals)

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

w_w = [ K' · ((4n'+2)/(3n'))^n' · (2q/(w·h))^(n'−1) · q · L / (E' · h) ]^(1/(2n'+2))

Maximum wellbore width for a propagating PKN fracture in a power-law fluid. Collapses byte-identically to the Newtonian Nordgren form (3·[μqL/E']^(1/4)·h^(-1/4)) when n' = 1 and K' = μ.

Used in

Fluid model panel — width preview chip

Net-pressure match — modeled Pnet for slickwater vs gel fluids

Module

src/lib/powerLawPknWidth.ts → pknWidth (widthModel: 'newtonian' | 'power-law')

Where

n' — power-law flow behaviour index [-]
K' — consistency index [Pa·s^n']
q — wing volumetric rate [m³/s]
h — fracture height [m]
L — fracture half-length [m]
E' — plane-strain modulus E/(1−ν²) [Pa]

Assumptions

Elliptical cross-section (PKN)
γ̇ ≈ 2q/(w·h) average gap shear rate
Picard fixed-point converges (typical ≤ 16 iterations)

Validity range

0.3 ≤ n' ≤ 1.0; K' from rheology card. For HVFR + slickwater hybrids the n'/K' values from FluidRheologyModel (Phase 1.2) feed in directly.

Units: SI (m, Pa·s^n', m³/s) — convert via unitsCanonical at call site

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

ΔP / L = (μ · v) / k + β · ρ · v²

Total pressure gradient in the propped pack — Darcy viscous term plus Forchheimer inertial term. The β coefficient comes from the proppant non-Darcy registry (§2.2).

Used in

/refrac deliverability card — advisory chip when v_pore > 0.1 m/s

/economics deliverability card — same advisory chip

Module

src/lib/proppantNonDarcyBeta.ts → nonDarcyBetaPerFt / inertialReynolds

Where

μ — fluid viscosity [Pa·s]
v — superficial pore velocity [m/s]
k — pack permeability [m²] (mD × 9.869e-16)
ρ — fluid density [kg/m³]
β — non-Darcy coefficient [1/m] (Cooke / Pursell form β = a/(k^b · φ^c))

Assumptions

Single-phase flow
Pack porosity from DEFAULT_PROPPED_POROSITY per family
Inertial losses meaningful only when Re_β > 0.1

Validity range

Gas wells and high-rate liquids; for low-rate oil wells the Darcy term dominates and β can be safely dropped.

Units: Pa/m (ΔP/L)

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

∂T/∂t + v(x) · ∂T/∂x = α · ∂²T/∂x²

Convection-diffusion temperature evolution along the fracture half-length. Wellbore BC = T_inj (Dirichlet); tip BC = ∂T/∂x = 0 (insulated). Output T(x, t) feeds breakerSchedule.ts so T½(x) and μ(t) decay vary along the fracture, not just at the wellbore.

Used in

Breaker schedule card — μ(t, x) heatmap (planned UI)

Fluid model panel — thermal-front chip (planned UI)

Module

src/lib/fractureTemperatureProfile.ts → fractureTemperatureProfile + breakerInputsAlongFracture

Where

T(x, t) — slurry temperature [°F]
v(x) — local slurry velocity along the fracture [ft/s]
α — effective thermal diffusivity [ft²/s] (default ≈ 1e-5)
T_inj — wellhead injection temperature [°F]
BHST — bottom-hole static temperature [°F] (initial condition)

Assumptions

1-D along-fracture flow (lateral averaging across height + width)
Explicit upwind FD scheme; CFL ≤ 1 and Fourier ≤ 0.5 enforced by sub-stepping
Slurry temperature dominates rock heat-up (rock-side conduction lumped into α)

Validity range

Tight unconventional rock; for high-permeability or geothermal cases use the coupled T-M-H kernel (thermoPoroGrid3D.ts) instead.

Units: °F, ft, s

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

v_eff = [ g · (ρ_p − ρ_f) · d² / (18 · μ) ] · (1 − d/w)² / (1 + 2.1·d/w) · (1 − φ)^n

Effective proppant settling velocity inside a hydraulic fracture — Stokes terminal velocity multiplied by the Francis-Boycott wall-effect factor and the Richardson-Zaki hindered-settling exponent. The regime classifier maps Π = v_eff / v_fluid_vertical onto suspended / hindered / settled bands shown on the live heatmap.

Used in

/live-pumping settling-regime heatmap — current operating point Π marker

Proppant transport panel — banking risk advisory

Module

src/lib/proppantSettlingRegimeMap.ts → evaluateSettlingRegime / buildSettlingRegimeMap

Where

v_eff — effective settling velocity [ft/s]
d — mean grain diameter [in], converted internally to ft
w — local fracture width [in]
μ — apparent fluid viscosity [cP], converted internally to lbm/(ft·s)
ρ_p, ρ_f — proppant and fluid densities [lbm/ft³] (from SG)
φ — in-situ proppant volume fraction (from ppa and proppant SG)
n — Richardson-Zaki exponent (default 4.65 for low-Re sand-in-water)

Assumptions

Newtonian carrier within the cell (power-law μ_app evaluated at γ̇ = 100 s⁻¹ when called from FluidRheologyModel)
Spherical proppant; aspect-ratio corrections folded into the apparent SG when applicable
Vertical fluid velocity approximated as q_slurry / (h_frac · w_frac)
Random-close-packing cap φ ≤ 0.6

Validity range

Re_p ≲ 1 (creeping flow). For Re_p ≳ 10 use a drag-law correction (Schiller-Naumann) outside the heatmap.

Units: ft/s

7. Sensitivity & calibration runs

How to set up a Design-of-Sensitivity (DS) sweep and what each parameter affects.

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

Recommended ranges (Bakken)

K_IC: 1,000–2,500 psi·√in · C_L: 0.0005–0.005 ft/√min · E: 3.5e6–6.5e6 psi · ν: 0.20–0.30. These match the DS ranges baked into the Bakken template.

8. Troubleshooting

Common 'I can't change X' issues and how to fix them.

Symptom	Likely cause	Fix
Save Changes is greyed out	No edits committed since last save, OR a Validate error is blocking the change.	Click outside the input to commit, then click Validate. Fix any red-flagged fields.
Sensitivity parameter doesn't change results	Sweep range too narrow, or the parameter is overridden by a calibration value.	Widen the range. Check Calibration → Active fits — fitted K_IC overrides Fracture options unless you Unlink.
Paste from Excel tab inserts blanks	Excel tab name doesn't match the panel id.	Rename the Excel tab to match (e.g. 'Wells_and_perforations') or use the per-panel column header template.
Run on Server stays in 'queued' forever	Server worker is paused or out of credits.	Open Settings → Compute and resume the worker. Local Run still works.
Results show — (em-dash) instead of numbers	That output wasn't computed for this case (e.g. proppant placement on a slickwater-only sim).	Check Output panel — enable the metric, re-run.
Wizard 'Apply' is disabled	One of the required fields failed realism check (red).	Open the Validation & warnings card — fix the listed fields.

9. Live operations & post-job analysis

Real-time pumping overlay, ISIP auto-pick, Nolte-Smith, decline analysis, step-down auto-detect, net-pressure history-match, fiber-optic streaming, and live auto-tuner.

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.

10. Sensitivity, optimization, parent-child & economics

Diagnostic Studies tornado, OFAT sweep, Optimum Finder (NM/PSO + Pareto), parent-child interference, and DCA + economics.

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).

11. Reservoir, wellbore, fluids & advanced physics

RESQML/GRDECL export, transient wellbore (single-phase + drift-flux), breaker schedule, FracPro slurry library, perf-cluster designer, layer tracers, adsorption.

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 (32 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, and methanol-water blend) feeds a stage-role chip filter; ρ_eff (slurry + proppant @ Cppa) cascades into Pressure Advisor mud weight → hydrostatic / ECD / surface budget / breakdown.

10.4b Fluid name resolution#

resolveSlurry(name) = STANDARD_SLURRY_LIBRARY.find(s => s.name == name) ?? error_chip(name)

How the simulator turns a fluid-name string from a schedule (Builder, CSV/JSON import, FracPro-style report) into a concrete rheology row. Unknown names raise an error chip — never a silent fallback to water.

Used in

Builder → SlurryLibraryPicker (stage-role chip filter)

Builder → Fluid model → FluidMixturePanel (per-stage fluid rows)

FracPro-style report (PDF + CSV) — Table 4 (Fluids) lookup

Scenario JSON IO — fluid-name validation on import

Module

src/lib/hfaSlurryLibrary.ts → STANDARD_SLURRY_LIBRARY · src/lib/fourStageFluidLink.ts

Where

name — fluid name as entered in the schedule (case-sensitive)
STANDARD_SLURRY_LIBRARY — 32-entry read-only catalog (src/lib/hfaSlurryLibrary.ts)
error_chip — surfaced inline on the Treatment / Fluid mixture panel and blocks Validate until resolved

Assumptions

Fluid catalog is the single source of truth — CSV/JSON ingest does NOT auto-create new entries
Unknown names are an authoring error, not a defaulting opportunity
Names are matched verbatim (no fuzzy-match) so library churn is visible at validate time

Validity range

Any panel/import that consumes a fluid name; applies to all 4 stage roles (preflush · pad · slurry · postflush).

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.

12. Reports & exports

Calibration report, FracPro-style report, scenario JSON IO, input bookmarks.

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.

13. Workspace toggles & UX

Reservoir type chip, table density, units & precision, keyboard shortcuts.

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.

14. Units & sanity checks

Canonical unit for every quantity, plus the hard/soft bounds the app uses to flag unit-confusion mistakes (m vs ft, °C vs °F, MPa vs psi).

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#

Quantity	Canonical	Also accepted	Convert
Length / depth	ft	m	1 m = 3.28084 ft
Pressure	psi	Pa, kPa, MPa, bar	1 MPa = 145.0377 psi
Stress	psi	Pa, MPa	Same as pressure
Temperature	°F	°C, K	°F = °C·9/5 + 32
Mud weight	ppg	kg/m³, sg	1 ppg = 119.826 kg/m³
Pump rate	bpm	m³/min, m³/s	1 bpm = 0.15899 m³/min
Proppant conc.	ppga	kg/m³	1 ppga ≈ 119.826 kg/m³ of clean fluid
Permeability	mD	m²	1 mD ≈ 9.869e-16 m²
Viscosity	cP	Pa·s	1 cP = 1e-3 Pa·s
Time	min	s, hr, day	Pumping = min; production = day

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).

Field	Unit	Hard min	Soft min	Soft max	Hard max
Depth (TVD or MD)	ft	0	200	25 000	40 000
Temperature (BHST)	°F	32	80	350	600
Pressure (BHP / surface)	psi	0	100	20 000	35 000

Where the bounds come from

Bands are sourced from src/lib/inputSanity.ts (DEPTH_BAND_FT, TEMPERATURE_BAND_F, PRESSURE_BAND_PSI). Use checkDepthFt / checkTemperatureF / checkPressurePsi from that module to wire the same severity into custom panels.

Common unit-confusion traps

Depth 50 ft → likely a metres entry (50 m ≈ 164 ft). Temperature 25 °F → likely °C (25 °C = 77 °F). Pressure 30 psi at downhole → likely MPa (30 MPa ≈ 4350 psi). Mud weight 1.2 ppg → likely sg (1.2 sg = 10.0 ppg).

15. Recently shipped (post-1.0)

Modules and physics added since the 1.0 manual: non-planar 3D solver, advanced rheology, refrac & live-ops upgrades, scenario branching, copilot palette, and more.

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.

16. Glossary

Industry terms used verbatim, plus the few names we changed.

Term	Meaning
Workspace (a.k.a. Sandbox)	Also called a 'Sandbox' in some simulators — a working set of related simulations sharing a base template.
Simulation	One numerical model. Edit, validate, run, and view results at this level.
DS run	Design-of-Sensitivity run — a parameter sweep across many simulations.
DFIT	Diagnostic Fracture Injection Test — short-injection field test used to fit T₀ and K_IC.
G-function	Time-transform used to identify fracture closure on a DFIT pressure trace.
K_IC	Mode-I fracture toughness — resistance of the rock to fracture-tip propagation.
C_L	Carter leak-off coefficient — fluid loss rate to the matrix per √time.
SH_min / SH_max	Minimum / maximum horizontal in-situ stress.
T₀	Tensile strength of the rock.
TVD	True vertical depth — vertical distance from surface to a downhole point.
BHST	Bottom-hole static temperature.
BHP	Bottom-hole pressure.
MD	Measured depth — distance along the wellbore from surface.
ppg	Pounds per gallon — common mud-weight unit.