petropt/petro-mcp

Query production data from a CSV file (columns: date, well_name, oil, gas, water).

Args: file_path: Absolute path to the production CSV file. well_name: Optional well name to filter by. start_date: Optional start date (YYYY-MM-DD). end_date: Optional end date (YYYY-MM-DD).

Analyze production trends and detect anomalies (shut-ins, rate jumps, water breakthrough, GOR blowouts).

Computes per-well water cut trend, GOR trend, oil decline rate, cumulative production, and flags anomalous events.

Args: file_path: Absolute path to the production CSV file. well_name: Optional well name to filter by.

Calculate producing ratios: GOR, WOR, water cut, and classify well type.

Args: oil_rate: Oil rate in bbl/day (BOPD). gas_rate: Gas rate in Mcf/day. water_rate: Water rate in bbl/day (BWPD).

Simplified nodal analysis: find IPR/VLP intersection for operating point.

Uses Vogel IPR and simplified vertical lift model.

Args: reservoir_pressure: Average reservoir pressure in psi. PI: Productivity index in bbl/day/psi. tubing_size: Tubing inner diameter in inches. wellhead_pressure: Wellhead flowing pressure in psi. depth: True vertical depth in feet (default 8000). fluid_gradient: Fluid pressure gradient in psi/ft (default 0.35).

Calculate comprehensive black-oil PVT properties at given conditions.

Returns bubble point, solution GOR, oil FVF, oil density, oil viscosity, gas Z-factor, gas FVF, gas viscosity, and gas compressibility.

Supported oil correlation sets: - 'standing' (default): Standing (1947) - 'vasquez_beggs': Vasquez and Beggs (1980) - 'petrosky_farshad': Petrosky and Farshad (1993)

Args: api_gravity: Oil API gravity (degrees). gas_sg: Gas specific gravity (air = 1.0). temperature: Reservoir temperature in F. pressure: Current reservoir pressure in psi. separator_pressure: Separator pressure in psi (default 100). separator_temperature: Separator temperature in F (default 60). correlation: Oil correlation set -- 'standing', 'vasquez_beggs', or 'petrosky_farshad'.

Calculate bubble point pressure using Standing's correlation (1947).

Args: api_gravity: Oil API gravity (degrees). gas_sg: Gas specific gravity (air = 1.0). temperature: Reservoir temperature in F. rs: Solution gas-oil ratio at bubble point in scf/STB.

Calculate oil compressibility above and below bubble point.

Uses Vasquez-Beggs (1980) above Pb and material-balance approach below Pb.

Args: api_gravity: Oil API gravity (degrees). gas_sg: Gas specific gravity (air = 1.0). temperature: Reservoir temperature in F. pressure: Current reservoir pressure in psi. bubble_point_pressure: Known bubble point pressure in psi (optional). rs_at_pb: Solution GOR at bubble point in scf/STB (optional).

Calculate brine/formation water PVT properties.

Returns density, viscosity, FVF, and compressibility using McCain (1990) and Osif (1988) correlations.

Args: temperature: Formation temperature in F. pressure: Formation pressure in psi. salinity: Total dissolved solids in ppm (default 0 = fresh water).

Calculate gas Z-factor with choice of correlation and pseudocritical method.

Z-factor methods: 'hall_yarborough' (default), 'dranchuk_abou_kassem'. Pseudocritical methods: 'sutton' (default), 'piper' (better for gas condensates and sour gases).

Args: temperature: Temperature in F. pressure: Pressure in psi. gas_sg: Gas specific gravity (air = 1.0). method: Z-factor correlation -- 'hall_yarborough' or 'dranchuk_abou_kassem'. pseudocritical_method: Pseudocritical method -- 'sutton' or 'piper'. h2s_fraction: Mole fraction of H2S (for Piper method, 0-1). co2_fraction: Mole fraction of CO2 (for Piper method, 0-1). n2_fraction: Mole fraction of N2 (for Piper method, 0-1).

Calculate shale volume (Vshale) from gamma ray log.

Methods: linear, larionov_tertiary, larionov_older, clavier.

Args: gr: Gamma ray reading (API units). gr_clean: GR in clean sand (API units). gr_shale: GR in pure shale (API units). method: Calculation method. Default 'linear'.

Calculate porosity from bulk density log.

Args: rhob: Bulk density (g/cc). rho_matrix: Matrix density (g/cc). Default 2.65 (sandstone). rho_fluid: Fluid density (g/cc). Default 1.0 (fresh water).

Calculate porosity from sonic (compressional) log.

Methods: wyllie (time-average), raymer (Raymer-Hunt-Gardner).

Args: dt: Interval transit time (us/ft). dt_matrix: Matrix transit time (us/ft). Default 55.5 (sandstone). dt_fluid: Fluid transit time (us/ft). Default 189.0. method: 'wyllie' or 'raymer'. Default 'wyllie'.

Quick-look porosity from neutron-density combination (RMS method).

Args: nphi: Neutron porosity (fraction v/v). dphi: Density porosity (fraction v/v).

Calculate effective porosity from total porosity and shale volume.

PHIE = PHIT * (1 - Vshale)

Args: phi_total: Total porosity (fraction v/v, 0-1). vshale: Shale volume (fraction v/v, 0-1).

Calculate water saturation using Archie equation (clean sands).

Sw = (a * Rw / (phi^m * Rt))^(1/n)

Args: rt: True formation resistivity (ohm-m). phi: Porosity (fraction v/v, 0-1). rw: Formation water resistivity (ohm-m). a: Tortuosity factor. Default 1.0. m: Cementation exponent. Default 2.0. n: Saturation exponent. Default 2.0.

Calculate water saturation using Simandoux equation (shaly sands).

Args: rt: True formation resistivity (ohm-m). phi: Porosity (fraction v/v, 0-1). rw: Formation water resistivity (ohm-m). vshale: Shale volume (fraction v/v, 0-1). rsh: Shale resistivity (ohm-m). a: Tortuosity factor. Default 1.0. m: Cementation exponent. Default 2.0. n: Saturation exponent. Default 2.0.

Calculate water saturation using Indonesian equation (high-Vshale formations).

Poupon and Leveaux (1971). Better than Archie/Simandoux for very shaly sands.

Args: rt: True formation resistivity (ohm-m). phi: Porosity (fraction v/v, 0-1). rw: Formation water resistivity (ohm-m). vshale: Shale volume (fraction v/v, 0-1). rsh: Shale resistivity (ohm-m). a: Tortuosity factor. Default 1.0. m: Cementation exponent. Default 2.0. n: Saturation exponent. Default 2.0.

Estimate permeability using Timur (1968) equation.

k = 0.136 * phi^4.4 / Swirr^2

Args: phi: Porosity (fraction v/v, 0-1). swirr: Irreducible water saturation (fraction v/v, 0-1).

Estimate permeability using Coates (1991) equation.

k = ((phi / C)^2 * (FFI / BVI))^2

Args: phi: Porosity (fraction v/v, 0-1). bvi: Bound volume irreducible (fraction v/v). ffi: Free fluid index (fraction v/v). c: Coates constant. Default 10.0.

Determine net pay by applying porosity, Sw, and Vshale cutoffs to log data.

Returns net pay thickness, net-to-gross, average properties over pay, and per-sample pay flags.

Args: depths: Measured depths (ft). phi: Porosity values (fraction v/v) at each depth. sw: Water saturation values (fraction v/v) at each depth. vshale: Shale volume values (fraction v/v) at each depth. phi_cutoff: Minimum porosity for pay. Default 0.06. sw_cutoff: Maximum water saturation for pay. Default 0.5. vsh_cutoff: Maximum Vshale for pay. Default 0.5.

Calculate hydrocarbon pore thickness (HPT = h * phi * (1-Sw) * NTG).

Args: thickness: Net or gross thickness (ft). phi: Average porosity (fraction v/v, 0-1). sw: Average water saturation (fraction v/v, 0-1). ntg: Net-to-gross ratio (0-1). Default 1.0.

Full discounted cash flow analysis for a well.

Takes production arrays (from decline forecast) plus economic assumptions. Returns NPV, IRR, payout period, profitability index, and monthly cash flows.

Args: monthly_oil_bbl: Monthly oil production (bbl) for each period. monthly_gas_mcf: Monthly gas production (Mcf) for each period. monthly_water_bbl: Monthly water production (bbl) for each period. oil_price_bbl: Oil price ($/bbl). gas_price_mcf: Gas price ($/Mcf). opex_monthly: Monthly operating expense ($). capex: Total capital expenditure ($), applied at time 0. royalty_pct: Royalty fraction (0-1). Default 0.125. tax_rate: Severance/production tax rate (0-1). Default 0.0. discount_rate: Annual discount rate for NPV. Default 0.10. working_interest: Working interest fraction (0-1). Default 1.0. net_revenue_interest: Net revenue interest fraction (0-1). Default 0.875.

Calculate Net Present Value from monthly cash flows.

NPV = sum(CF_t / (1 + r/12)^t) for t = 0, 1, 2, ...

Args: cash_flows: Monthly cash flows ($). First element is typically negative (capex). discount_rate: Annual discount rate. Default 0.10.

Calculate Internal Rate of Return via bisection.

IRR is the annual discount rate at which NPV = 0.

Args: cash_flows: Monthly cash flows ($). First element is typically negative (capex).

Calculate PV10 -- SEC standard present value at 10% annual discount.

PV10 = sum(NR_t / 1.10^(t/12))

Args: monthly_net_revenue: Monthly net revenue ($) after royalties and opex.

Calculate breakeven oil price -- minimum price for NPV = 0.

Uses bisection to find the oil price at which discounted net cash flow equals zero.

Args: monthly_production_bbl: Monthly oil production (bbl) per period. monthly_opex: Monthly operating expense ($). capex: Total capital expenditure ($). discount_rate: Annual discount rate. Default 0.10. royalty_pct: Royalty fraction (0-1). Default 0.125. months: Number of months to evaluate (default: length of production array).

Calculate operating netback per BOE.

Revenue - royalties - opex - transport per BOE. Gas at 6 Mcf/BOE.

Args: oil_price: Oil price ($/bbl). gas_price: Gas price ($/Mcf). oil_rate_bpd: Oil production rate (bbl/day). gas_rate_mcfd: Gas production rate (Mcf/day). opex_per_boe: Operating expense per BOE ($/BOE). royalty_pct: Royalty fraction (0-1). Default 0.125. transport_per_boe: Transportation cost per BOE ($/BOE). Default 0.0.

Calculate payout period -- months to recover initial investment.

Payout is the first month where cumulative cash flow >= 0.

Args: cash_flows: Monthly cash flows ($). First element is typically negative (capex).

Calculate NPV across multiple price scenarios for sensitivity/tornado charts.

Args: monthly_oil_bbl: Monthly oil production (bbl) per period. monthly_gas_mcf: Monthly gas production (Mcf) per period. monthly_water_bbl: Monthly water production (bbl) per period. opex_monthly: Monthly operating expense ($). capex: Total capital expenditure ($). price_scenarios: List of dicts with 'oil_price' and 'gas_price'. discount_rate: Annual discount rate. Default 0.10. royalty_pct: Royalty fraction (0-1). Default 0.125.

Calculate hydrostatic pressure (P = 0.052 * MW * TVD).

Args: mud_weight_ppg: Mud weight in pounds per gallon (ppg). tvd_ft: True vertical depth in feet.

Calculate equivalent circulating density (ECD = MW + APL / (0.052 * TVD)).

Args: mud_weight_ppg: Static mud weight (ppg). annular_pressure_loss_psi: Annular pressure loss (psi). tvd_ft: True vertical depth (ft).

Calculate formation pressure gradient as ppg equivalent (FPG = P / (0.052 * TVD)).

Args: pressure_psi: Formation pressure (psi). tvd_ft: True vertical depth (ft).

Calculate kill mud weight for well control (Kill MW = MW + SIDP / (0.052 * TVD)).

Args: sidp_psi: Shut-in drill pipe pressure (psi). original_mud_weight_ppg: Original mud weight (ppg). tvd_ft: True vertical depth (ft).

Calculate Initial and Final Circulating Pressures for well kill operations.

ICP = SIDP + slow circulating pressure. FCP = SCP * (Kill MW / Original MW).

Args: sidp_psi: Shut-in drill pipe pressure (psi). circulating_pressure_psi: Slow circulating pressure (psi). kill_mud_weight_ppg: Kill mud weight (ppg). original_mud_weight_ppg: Original mud weight (ppg).

Calculate Maximum Allowable Annular Surface Pressure.

MAASP = (FG - MW) * 0.052 * shoe TVD.

Args: fracture_gradient_ppg: Fracture gradient at shoe (ppg). mud_weight_ppg: Current mud weight (ppg). shoe_tvd_ft: Casing shoe TVD (ft).

Calculate annular velocity (AV = 24.51 * Q / (Dh^2 - Dp^2)).

Args: flow_rate_gpm: Flow rate in gallons per minute. hole_diameter_in: Hole or casing ID (inches). pipe_od_in: Pipe or drill string OD (inches).

Calculate total flow area (TFA) of bit nozzles.

TFA = sum(pi/4 * (d/32)^2) for each nozzle size in 32nds of an inch.

Args: nozzle_sizes: List of nozzle sizes in 32nds of an inch (e.g. [12, 12, 12]).

Calculate pressure drop across the bit (dP = MW * Q^2 / (12032 * TFA^2)).

Args: flow_rate_gpm: Flow rate in gallons per minute. mud_weight_ppg: Mud weight (ppg). tfa_sqin: Total flow area of nozzles (in^2).

Calculate internal burst pressure using Barlow's formula with API 12.5% tolerance.

P_burst = 0.875 * 2 * Fy * t / OD.

Args: yield_strength_psi: Minimum yield strength (psi). wall_thickness_in: Nominal wall thickness (inches). od_in: Outer diameter (inches).

Calculate collapse pressure rating per API 5C3.

Determines regime (yield, plastic, transition, elastic) from D/t ratio and yield strength, then applies the corresponding API formula.

Args: od_in: Casing outer diameter (inches). wall_thickness_in: Wall thickness (inches). yield_strength_psi: Minimum yield strength (psi). grade: Optional API grade label (e.g. 'N-80') for reference.

Parse a LAS 2.0 well log file and return header info and curve data summary.

Args: file_path: Absolute path to the LAS file.

Extract well header metadata (well name, UWI, location, KB, TD, etc.) from a LAS file.

Args: file_path: Absolute path to the LAS file.

List all curves in a LAS file with their units and descriptions.

Args: file_path: Absolute path to the LAS file.

Get specific curve data from a LAS file with optional depth range filtering.

Args: file_path: Absolute path to the LAS file. curve_names: List of curve mnemonics to retrieve (e.g., ["GR", "RHOB"]). start_depth: Optional start depth for filtering. end_depth: Optional end depth for filtering.

Beggs & Brill (1973) multiphase pressure drop in pipes.

The most widely used multiphase flow correlation. Determines flow pattern, calculates liquid holdup, friction factor, and pressure gradient including elevation, friction, and acceleration terms.

Args: flow_rate_bpd: Total liquid flow rate in bbl/day. gor_scf_bbl: Gas-oil ratio in scf/bbl. water_cut: Water cut as fraction (0-1). oil_api: Oil API gravity. gas_sg: Gas specific gravity (air = 1.0). pipe_id_in: Pipe inner diameter in inches. pipe_length_ft: Pipe length in feet. inclination_deg: Pipe inclination from horizontal (-90 to 90 degrees). wellhead_pressure_psi: Wellhead (outlet) pressure in psi. temperature_f: Average flowing temperature in degrees F.

Turner et al. (1969) critical rate for gas well liquid unloading.

Calculates the minimum gas velocity and flow rate needed to continuously lift liquids from a gas well using the droplet model.

Args: wellhead_pressure_psi: Wellhead flowing pressure in psi. wellhead_temp_f: Wellhead temperature in degrees F. gas_sg: Gas specific gravity (air = 1.0). condensate_sg: Condensate specific gravity (optional). water_sg: Water specific gravity. Default 1.07. tubing_id_in: Tubing inner diameter in inches. Default 2.441. current_rate_mcfd: Current gas rate in Mcf/d for status check (optional).

Coleman et al. (1991) critical rate for liquid loading (20% below Turner).

Recommended for low-pressure gas wells (< ~500 psi wellhead pressure).

Args: wellhead_pressure_psi: Wellhead flowing pressure in psi. wellhead_temp_f: Wellhead temperature in degrees F. gas_sg: Gas specific gravity (air = 1.0). tubing_id_in: Tubing inner diameter in inches. Default 2.441. current_rate_mcfd: Current gas rate in Mcf/d for status check (optional).

Estimate hydrate formation temperature using gas-gravity method (Katz chart).

Args: pressure_psi: System pressure in psi. gas_sg: Gas specific gravity (air = 1.0, range 0.55-1.0).

Calculate hydrate inhibitor injection rate using Hammerschmidt equation.

Supports methanol, MEG, and ethanol.

Args: hydrate_temp_f: Hydrate formation temperature in degrees F. operating_temp_f: Target operating temperature in degrees F. water_rate_bwpd: Water production rate in bbl/day. inhibitor: Inhibitor type - 'methanol', 'meg', or 'ethanol'.

Calculate erosional velocity per API RP 14E (v_e = C / sqrt(rho_mix)).

Args: density_mix_lb_ft3: Mixture density in lb/ft3. c_factor: Erosional constant. Default 100. Use 125 for intermittent, 150-200 for corrosion-resistant alloys.

Calculate flow rate through a choke using Gilbert correlation (1954).

q = P * S^1.89 / (435 * GLR^0.546). Valid for critical (sonic) flow only.

Args: upstream_pressure_psi: Upstream pressure in psi. choke_size_64ths: Choke bean size in 64ths of an inch. gor_scf_bbl: Gas-oil ratio in scf/bbl. oil_api: Oil API gravity. water_cut: Water cut as fraction (0-1). Default 0.0. gas_sg: Gas specific gravity. Default 0.65.

Normalize production rate by pressure drawdown: q / (Pi - Pwf).

Removes the effect of variable flowing pressure from production data, making it suitable for type curve analysis and RTA.

Args: rate: Production rates (bbl/d or Mcf/d). flowing_pressure: Bottomhole flowing pressures (psi). initial_pressure: Initial reservoir pressure (psi).

Compute material balance time: tMB = Np / q.

The Blasingame x-axis transform that converts variable-rate production into an equivalent constant-rate time for decline type curve matching.

Args: cumulative_production: Cumulative production values. rate: Instantaneous production rates.

Compute Blasingame rate-normalized integral and derivative for type curve matching.

Calculates material balance time, normalized rate, rate-integral, and rate-integral-derivative used for Blasingame decline type curve analysis.

Args: times: Time values (days or months). rates: Production rates. cumulative: Cumulative production. flowing_pressures: Bottomhole flowing pressures (psi). initial_pressure: Initial reservoir pressure (psi).

Compute Agarwal-Gardner rate-normalized variables for type curve analysis.

Calculates normalized rate q/(Pi-Pwf), inverse normalized rate, cumulative-normalized production, and material balance time.

Args: times: Time values (days or months). rates: Production rates. cumulative: Cumulative production. flowing_pressures: Bottomhole flowing pressures (psi). initial_pressure: Initial reservoir pressure (psi).

Compute Normalized Pressure Integral (NPI) for flowing material balance.

NPI integrates the pressure-normalized rate over time to smooth noisy production data. Used for flow regime identification and FMB analysis.

Args: times: Time values (days or months). rates: Production rates. flowing_pressures: Bottomhole flowing pressures (psi). initial_pressure: Initial reservoir pressure (psi).

Flowing Material Balance: estimate OOIP/OGIP from production data.

Plots q/(Pi-Pwf) vs normalized cumulative production. The x-intercept of the regression line gives the contacted hydrocarbon volume.

Args: rates: Production rates (bbl/d or Mcf/d). flowing_pressures: Bottomhole flowing pressures (psi). initial_pressure: Initial reservoir pressure (psi). fluid_fvf: Formation volume factor (rb/stb or rcf/scf). total_compressibility: Total system compressibility (1/psi).

Square root of time analysis for linear flow identification.

During fracture-dominated linear flow, (Pi-Pwf)/q vs sqrt(t) is a straight line. The slope is used to determine sqrt(k)*xf.

Args: rates: Production rates (bbl/d or Mcf/d). times: Time values (days). flowing_pressures: Bottomhole flowing pressures (psi). initial_pressure: Initial reservoir pressure (psi).

Extract permeability from RTA linear flow analysis.

Uses the slope from sqrt(t) analysis to calculate either permeability (if fracture half-length is known) or the sqrt(k)*xf product.

Args: slope_from_linear_flow: Slope from sqrt(t) analysis (psi*d/bbl/d^0.5). net_pay_ft: Net pay thickness (ft). porosity: Porosity (fraction, 0-1). viscosity_cp: Fluid viscosity (cp). total_compressibility: Total compressibility (1/psi). fracture_half_length_ft: Fracture half-length (ft). If None, returns sqrt(k)*xf.

Monte Carlo EUR estimation with P10/P50/P90 (reserve report ready).

Samples qi, Di, and b-factor from lognormal (or normal) distributions, computes EUR for each realization using Arps hyperbolic decline, and returns probabilistic reserve estimates.

Args: qi_mean: Mean initial production rate (bbl/day or Mcf/day). qi_std: Standard deviation of initial rate. di_mean: Mean initial decline rate (1/month, nominal). di_std: Standard deviation of decline rate. b_mean: Mean Arps b-factor (default 1.0). b_std: Standard deviation of b-factor (default 0.3). economic_limit: Minimum economic rate (default 5.0). num_simulations: Number of Monte Carlo realizations (default 10000). distribution: Sampling distribution - 'lognormal' or 'normal'.

Bootstrap decline curve parameters from production data.

Resamples production data with replacement, refits the decline model each time, and returns confidence intervals on parameters and EUR.

Args: production_data: List of dicts with 'time' (months) and 'rate' keys. model: Decline model - 'exponential', 'hyperbolic', or 'harmonic'. num_bootstrap: Number of bootstrap iterations (default 1000).

Fit a statistical distribution to EUR values for P10/P50/P90.

Takes a list of EUR values (from Monte Carlo, bootstrapping, or analog wells) and fits a lognormal or normal distribution. Returns percentiles, distribution parameters, and Kolmogorov-Smirnov goodness of fit.

Args: eur_values: List of EUR values. distribution: Distribution to fit - 'lognormal' or 'normal'.

Sensitivity analysis on decline parameters for tornado chart data.

Varies each parameter (qi, Di, b, economic limit) independently and computes EUR at low/high values. Returns data sorted by impact for tornado chart visualization.

Args: qi: Base initial rate (bbl/day or Mcf/day). di: Base initial decline rate (1/month). b: Base Arps b-factor. economic_limit: Minimum economic rate (default 5.0). parameter_ranges: Optional dict mapping parameter name to [low, high]. Defaults to +/-20% of base values.

Generate P10/P50/P90 rate-time forecast profiles.

Unlike mc_eur which returns only EUR summaries, this generates the full rate-time curves at each percentile. Output includes downsampled rate profiles and cumulative production milestones at 1/3/5/10/20/30 years.

Args: qi_dist: Dict with 'mean' and 'std' for initial rate. di_dist: Dict with 'mean' and 'std' for decline rate. b_dist: Dict with 'mean' and 'std' for b-factor. forecast_months: Forecast duration in months (default 360 = 30 years). economic_limit: Minimum economic rate (default 5.0). num_simulations: Number of realizations (default 1000).

Gas material balance: P/Z vs cumulative gas production analysis.

Fits a linear P/Z vs Gp trend to estimate Original Gas In Place (OGIP). The #1 reservoir engineering spreadsheet calculation.

Args: pressures: Reservoir pressures (or P/Z values) in psi at each time step. cumulative_gas: Cumulative gas production in Bcf at each pressure. abandonment_pressure: Optional abandonment pressure in psi for recoverable gas estimate.

Oil material balance using Havlena-Odeh straight-line method (1963).

Identifies drive mechanism (depletion, gas cap, water drive) and estimates Original Oil In Place (OOIP). Returns F vs Et plot data for diagnostics.

Args: pressures: Reservoir pressures at each time step (psi). np_values: Cumulative oil production at each step (STB). rp_values: Cumulative producing GOR at each step (scf/STB). wp_values: Cumulative water production at each step (STB). wi_values: Cumulative water injection at each step (STB). bo_values: Oil FVF at each pressure (bbl/STB). rs_values: Solution GOR at each pressure (scf/STB). bg_values: Gas FVF at each pressure (bbl/scf). bw_values: Water FVF at each pressure (bbl/STB). boi: Initial oil FVF (bbl/STB). rsi: Initial solution GOR (scf/STB). bgi: Initial gas FVF (bbl/scf). cf: Formation compressibility (1/psi). Optional. swi: Initial water saturation (fraction, 0-1). Optional.

Calculate volumetric Original Oil In Place (OOIP).

OOIP = 7758 * A * h * phi * (1-Sw) / Bo (STB)

Args: area_acres: Reservoir area in acres. thickness_ft: Net pay thickness in feet. porosity: Porosity (fraction, 0-1). sw: Water saturation (fraction, 0-1). bo: Oil formation volume factor (bbl/STB).

Calculate volumetric Original Gas In Place (OGIP).

OGIP = 43560 * A * h * phi * (1-Sw) / Bg (scf)

Args: area_acres: Reservoir area in acres. thickness_ft: Net pay thickness in feet. porosity: Porosity (fraction, 0-1). sw: Water saturation (fraction, 0-1). bg: Gas formation volume factor (ft3/scf).

Calculate recovery factor (RF = Np/N or Gp/G).

Works for both oil and gas -- just use consistent units.

Args: ooip_or_ogip: Original oil or gas in place. cumulative_production: Cumulative production (same units).

Calculate radius of investigation for a well test.

r_inv = 0.029 * sqrt(kt / (phimu*ct)), from Lee (1982).

Args: permeability_md: Formation permeability in millidarcies. time_hours: Elapsed time in hours. porosity: Porosity (fraction, 0-1). viscosity_cp: Fluid viscosity in centipoise. total_compressibility: Total system compressibility in 1/psi.

Fit decline curves to production data.

Supports Arps models (exponential, hyperbolic, harmonic), modified hyperbolic with Dmin terminal decline switch, and Duong model for unconventional/shale wells with fracture-dominated flow.

Returns fitted parameters, R-squared, and predicted rates. Physics-constrained: b-factor bounded to [0, 2], non-negative rates enforced.

Args: production_data: List of dicts with 'time' (months) and 'rate' keys, or 'oil'/'gas' keys (time assumed as sequential months). model: Decline model - 'exponential', 'hyperbolic', 'harmonic', 'modified_hyperbolic', or 'duong'.

Calculate Estimated Ultimate Recovery using decline parameters.

Supports Arps models (exponential, hyperbolic, harmonic), modified hyperbolic with Dmin terminal decline switch, and Duong model for unconventional/shale wells.

Args: qi: Initial production rate (bbl/day or Mcf/day). Di: Initial decline rate (1/month, nominal). Used by exponential, hyperbolic, harmonic, and modified_hyperbolic models. b: Arps b-factor (0=exponential, 1=harmonic, 0-2=hyperbolic). economic_limit: Minimum economic rate (same units as qi). model: Decline model - 'exponential', 'hyperbolic', 'harmonic', 'modified_hyperbolic', or 'duong'. Dmin: Minimum terminal decline rate for modified_hyperbolic (1/month). a: Duong intercept parameter (typically 0.5-2.0). m: Duong slope parameter (typically 1.0-1.5).

Fit Power Law Exponential (PLE) decline model to production data.

The PLE model (Ilk et al., 2008) captures transient and boundary-dominated flow regimes in tight/shale reservoirs. Uses petbox-dca for the forward model.

Args: production_data: List of dicts with 'time' (months) and 'rate' keys, or 'oil'/'gas' keys (time assumed as sequential months).

Fit Duong decline model to production data using petbox-dca.

The Duong model (2011) is designed for fracture-dominated flow in unconventional/shale reservoirs. Widely used for tight oil and shale gas.

Args: production_data: List of dicts with 'time' (months) and 'rate' keys, or 'oil'/'gas' keys (time assumed as sequential months).

Fit Stretched Exponential (SEPD) decline model to production data.

The SEPD model (Valko, 2009) uses a stretched exponential function effective for unconventional reservoirs with heterogeneous fracture networks.

Args: production_data: List of dicts with 'time' (months) and 'rate' keys, or 'oil'/'gas' keys (time assumed as sequential months).

Forecast production using an advanced decline model (PLE, Duong, SEPD, THM).

Generates rate-time forecast and cumulative production using petbox-dca models. Use parameters from fit_ple_decline, fit_duong_decline, or fit_sepd_decline, or provide THM parameters directly.

Args: model: Model name - 'ple', 'duong', 'sepd', or 'thm'. parameters: Dict of model parameters. PLE: qi, Di, Dinf, n Duong: qi, a, m SEPD: qi, tau, n THM: qi, Di, bi, bf, telf (optional: bterm, tterm) forecast_months: Number of months to forecast (default 360 = 30 years). economic_limit: Minimum economic rate in vol/day (default 5.0).

Calculate well trajectory using minimum curvature method.

Takes survey station data (MD, inclination, azimuth) and returns computed North, East, TVD, and dogleg severity at each station.

Args: md: List of measured depths (ft or m). inclination: List of inclinations (degrees from vertical, 0-180). azimuth: List of azimuths (degrees from north, 0-360). unit: Depth unit -- 'feet' or 'meters'. Default 'feet'.

Calculate dogleg severity between two survey stations.

Returns DLS in deg/100ft (or deg/30m for metric).

Args: md1: Measured depth at station 1. inc1: Inclination at station 1 (degrees). azi1: Azimuth at station 1 (degrees). md2: Measured depth at station 2. inc2: Inclination at station 2 (degrees). azi2: Azimuth at station 2 (degrees). course_length_unit: 'feet' or 'meters'. Default 'feet'.

Project well trajectory onto a vertical section plane.

Calculates the horizontal displacement projected onto a plane at the given azimuth. Standard way to view a well path in 2D cross-section.

Args: md: List of measured depths. inclination: List of inclinations (degrees). azimuth: List of azimuths (degrees). vs_azimuth: Vertical section azimuth in degrees (0 = North). Default 0. unit: Depth unit -- 'feet' or 'meters'. Default 'feet'.

Calculate wellbore tortuosity index from survey data.

Tortuosity measures how much the wellbore deviates from an ideal path. Higher values indicate more tortuous wellpath, impacting drilling and production operations.

Args: md: List of measured depths. inclination: List of inclinations (degrees). azimuth: List of azimuths (degrees). unit: Depth unit -- 'feet' or 'meters'. Default 'feet'.

Check separation between two wells at closest approach.

Computes center-to-center distance between two well trajectories and identifies the closest approach point.

Args: well1_md: Measured depths for reference well. well1_inc: Inclinations for reference well (degrees). well1_azi: Azimuths for reference well (degrees). well2_md: Measured depths for offset well. well2_inc: Inclinations for offset well (degrees). well2_azi: Azimuths for offset well (degrees). well2_start_north: Offset well surface location north of reference. well2_start_east: Offset well surface location east of reference. unit: Depth unit -- 'feet' or 'meters'. Default 'feet'.

Convert between oilfield and SI units.

Supports volume (bbl, m3, gal, liters, Mcf, MMcf, Bcf), rate (bbl/day, m3/day, Mcf/day, bbl/month), pressure (psi, kPa, MPa, bar, atm), length (ft, m, in, cm, miles, km), density (g/cc, kg/m3, lb/ft3, API gravity, SG), temperature (F, C, K), permeability (md, m2), viscosity (cp, Pa.s), and energy/BOE (BOE, MMBtu, Mcf_gas).

Args: value: Numeric value to convert. from_unit: Source unit (e.g. 'bbl', 'psi', 'API'). to_unit: Target unit (e.g. 'm3', 'kPa', 'SG').

List all supported oilfield unit categories and their units.