resaid 0.2.0

Comprehensive reservoir engineering tools for decline curve analysis and production forecasting

RESAID Package

A comprehensive collection of reservoir engineering tools for production forecasting and decline curve analysis.

Features

• Decline Curve Analysis (DCA): Arps decline curve fitting with exponential, hyperbolic, and harmonic decline models
• Production Data Processing: Normalization, outlier detection, and data preprocessing
• Single-Phase Forecasting: Traditional major phase analysis with ratio-based minor phase estimation
• Three-Phase Forecasting: Independent decline curve analysis for OIL, GAS, and WATER phases
• Multiple Output Formats: Flowstream, oneline, and typecurve generation
• Economic Analysis: NPV, IRR, and comprehensive cashflow modeling
• Multi-Phase Economics: Oil, gas, water, and NGL revenue calculations
• Royalty & Interest Modeling: Working interest, net revenue interest, and royalty calculations
• Tax & Cost Modeling: Severance taxes, ad valorem taxes, and operating costs
• Vectorized Operations: High-performance calculations for large datasets

Installation

pip install resaid

Quick Start

Basic Single-Phase DCA Analysis

import pandas as pd
from resaid.dca import decline_curve

# Load production data
prod_df = pd.read_csv('production_data.csv')

# Initialize DCA object
dca = decline_curve()

# Configure data columns
dca.dataframe = prod_df
dca.date_col = 'ProducingMonth'
dca.uid_col = 'API_UWI'
dca.oil_col = 'LiquidsProd_BBL'
dca.gas_col = 'GasProd_MCF'
dca.water_col = 'WaterProd_BBL'
dca.length_col = 'LateralLength_FT'

# Set analysis parameters
dca.min_h_b = 0.9
dca.max_h_b = 1.3
dca.backup_decline = True
dca.OUTLIER_CORRECTION = False

# Run DCA analysis
dca.run_DCA()

# Generate outputs
dca.generate_oneline(num_months=1200, denormalize=True)
dca.generate_flowstream(num_months=1200, denormalize=True)
dca.generate_typecurve(num_months=1200, denormalize=True)

# Access results
oneline_results = dca.oneline_dataframe
flowstream_results = dca.flowstream_dataframe
typecurve_results = dca.typecurve

Three-Phase Forecasting Mode

# Enable three-phase mode
dca.three_phase_mode = True

# Run analysis (same as before)
dca.run_DCA()

# Generate outputs with independent phase analysis
dca.generate_oneline(num_months=1200, denormalize=True)
dca.generate_flowstream(num_months=1200, denormalize=True)
dca.generate_typecurve(num_months=1200, denormalize=True)

# Three-phase results include phase-specific parameters
oneline_3p = dca.oneline_dataframe
print("Phase-specific columns:", [col for col in oneline_3p.columns if col.startswith(('IPO', 'IPG', 'IPW', 'DO', 'DG', 'DW', 'BO', 'BG', 'BW'))])

Economic Analysis

RESAID provides comprehensive economic analysis tools for oil and gas projects, including NPV calculations, IRR analysis, and detailed cashflow modeling.

Basic NPV and IRR Calculations

from resaid.econ import npv_calc

# Create cashflow array (negative for outflows, positive for inflows)
cashflow = np.array([-1000000, 500000, 400000, 300000, 200000])

# Initialize NPV calculator
npv = npv_calc(cashflow)

# Calculate NPV at 10% discount rate
npv_value = npv.get_npv(0.1)
print(f"NPV at 10%: ${npv_value:,.2f}")

# Calculate Internal Rate of Return
irr = npv.get_irr()
print(f"IRR: {irr:.1f}%")

Well Economics Analysis

from resaid.econ import well_econ

# Initialize economics calculator
econ = well_econ(verbose=False)

# Set flowstream data (from DCA analysis)
econ.flowstreams = dca.flowstream_dataframe
econ.flowstream_uwi_col = 'UID'
econ.flowstream_t_index = 'T_INDEX'

# Set header data with well information
header_data = pd.DataFrame({
    'UID': ['WELL001', 'WELL002'],
    'NRI': [0.8, 0.75],  # Net Revenue Interest
    'WI': [1.0, 1.0],    # Working Interest
    'CAPEX': [2000000, 1800000]  # Capital expenditure
})
econ.header_data = header_data
econ.header_uwi_col = 'UID'
econ.wi_col = 'WI'
econ.nri_col = 'NRI'
econ.capex_col = 'CAPEX'

# Set economic parameters
econ.oil_pri = 50.0      # Oil price $/bbl
econ.gas_pri = 3.0       # Gas price $/MCF
econ.discount_rate = 0.1 # 10% discount rate

# Operating costs
econ._opc_t = 1000       # Fixed operating cost $/month
econ._opc_oil = 5.0      # Variable oil cost $/bbl
econ._opc_gas = 0.5      # Variable gas cost $/MCF
econ._opc_water = 2.0    # Variable water cost $/bbl

# Taxes
econ._sev_oil = 0.05     # Oil severance tax rate
econ._sev_gas = 0.05     # Gas severance tax rate
econ._atx = 0.02         # Ad valorem tax rate

# Generate cashflow for all wells
cashflow = econ.generate_cashflow()

# Generate economic indicators
econ.generate_indicators()
indicators = econ.indicators

print("Economic Indicators:")
print(indicators[['UID', 'IRR', 'DCF', 'PAYOUT', 'BREAKEVEN']])

Advanced Economic Modeling

# Gas processing and NGL modeling
econ._gas_shrink = 0.1        # 10% gas shrinkage
econ._ngl_yield = 0.05        # 5 bbl NGL per MCF gas
econ._ngl_price_fraction = 0.6 # NGL price as fraction of oil price

# Price differentials
econ._oil_diff = -2.0         # Oil price differential $/bbl
econ._gas_diff = 0.5          # Gas price differential $/MCF

# Scaling and timing
econ._scale_forecast = True   # Scale forecast by well characteristics
econ._scale_column = 'LateralLength_FT'
econ._scale_base = 5280       # Base lateral length for scaling

# Generate well-specific cashflow
well_cashflow = econ.well_flowstream('WELL001')
print("Well cashflow columns:", list(well_cashflow.columns))

Economic Outputs

The economic analysis generates comprehensive outputs:

Cashflow DataFrame includes:

• Revenue streams: oil_revenue, gas_revenue, ngl_revenue
• Costs: expense, royalty, taxes, capex
• Cashflow: cf (undiscounted), dcf (discounted)
• Working interest: wi_* columns for WI calculations
• Net interest: net_* columns for NRI calculations

Economic Indicators include:

• IRR: Internal Rate of Return (%)
• DCF: Discounted Cash Flow ($)
• ROI: Return on Investment
• PAYOUT: Payback period (months)
• BREAKEVEN: Breakeven price ($/bbl or $/MCF)
• EURO, EURG, EURW: Estimated Ultimate Recovery by phase

Data Requirements

Input Data Format

Your production data should include the following columns:

• Date Column: Production date (e.g., 'ProducingMonth')
• Well Identifier: Unique well ID (e.g., 'API_UWI')
• Production Data: Oil, gas, and water production volumes
• Well Characteristics: Lateral length, hole direction, etc.

Example Data Structure

API_UWI,ProducingMonth,LiquidsProd_BBL,GasProd_MCF,WaterProd_BBL,LateralLength_FT
123456789,2020-01-01,1500,2500,500,8000
123456789,2020-02-01,1400,2400,480,8000
...

Configuration Options

DCA Parameters

• min_h_b, max_h_b: B-factor bounds for horizontal wells
• DEFAULT_DI: Default initial decline rate
• DEFAULT_B: Default Arps b-factor
• D_MIN: Minimum decline rate
• GAS_CUTOFF: Gas-oil ratio threshold for phase classification

Analysis Settings

• backup_decline: Enable backup decline rate for failed fits
• OUTLIER_CORRECTION: Enable outlier detection and filtering
• IQR_LIMIT: Outlier detection threshold
• FILTER_BONFP: Bonferroni correction threshold
• three_phase_mode: Enable three-phase forecasting

Economic Parameters

• oil_pri, gas_pri: Commodity prices ($/bbl, $/MCF)
• discount_rate: Discount rate for NPV calculations
• _opc_t, _opc_oil, _opc_gas, _opc_water: Operating costs
• _sev_oil, _sev_gas: Severance tax rates
• _atx: Ad valorem tax rate
• _gas_shrink, _ngl_yield: Gas processing parameters
• _scale_forecast: Enable production scaling by well characteristics

Output Formats

Oneline Results

Single-well summary with decline parameters and cumulative production:

• UID: Well identifier
• MAJOR: Major phase (OIL/GAS)
• OIL, GAS, WATER: Cumulative production
• IPO, IPG, IPW: Initial production rates
• DE, DO, DG, DW: Decline rates
• B, BO, BG, BW: Arps b-factors
• ARIES_DE, ARIES_DO, ARIES_DG, ARIES_DW: Aries-compatible decline rates

Flowstream Results

Monthly production forecasts for each well:

• Multi-index DataFrame with [UID, T_INDEX]
• OIL, GAS, WATER: Monthly production rates
• Time series from T_INDEX=0 to specified number of months

Typecurve Results

Statistical aggregation of decline parameters:

• Probability distributions (P10, P50, P90)
• Phase-specific parameter statistics
• Aggregated production forecasts

Economic Results

Comprehensive economic analysis outputs:

• Cashflow DataFrame: Monthly cashflow with revenue, costs, and cashflow streams
• Economic Indicators: IRR, NPV, ROI, payback period, and breakeven analysis
• Working Interest Calculations: WI-adjusted cashflows and metrics
• Net Revenue Interest: NRI-adjusted cashflows and economic indicators

Advanced Usage

Custom Decline Curve Solver

from resaid.dca import decline_solver

# Solve for missing parameters
solver = decline_solver(
    qi=1000,      # Initial rate
    qf=100,       # Final rate
    eur=50000,    # Estimated ultimate recovery
    b=1.0,        # Arps b-factor
    dmin=0.01/12  # Minimum decline rate
)

qi, t_max, qf, de, eur, warning, delta = solver.solve()

Parameter Optimization

# Customize analysis parameters
dca.min_h_b = 0.5
dca.max_h_b = 2.0
dca.DEFAULT_DI = 0.6/12
dca.DEFAULT_B = 0.8
dca.GAS_CUTOFF = 2.5  # MSCF/STB

# Run analysis with custom settings
dca.run_DCA()

Advanced Economic Modeling

# Price forecasting with time-varying prices
econ.oil_pri = [45.0, 50.0, 55.0, 60.0, 65.0]  # Price forecast
econ.gas_pri = [2.5, 3.0, 3.5, 4.0, 4.5]       # Gas price forecast

# Complex royalty structures
econ.royalty_col = 'ROYALTY_RATE'      # Column with well-specific royalty rates
econ.owned_royalty_col = 'OWNED_ROY'   # Column with owned royalty interest

# Scaled CAPEX based on well characteristics
econ.scale_capex = True
econ.scale_column = 'LateralLength_FT'
econ.capex_val = 250000  # Base CAPEX per 1000 ft

# Timing adjustments
econ.spud_to_online = 3  # Months from spud to first production
econ.t_start_column = 'FIRST_PROD_MONTH'  # Column with first production month

# Generate comprehensive economic analysis
cashflow = econ.generate_cashflow()
econ.generate_indicators()

# Access detailed results
print("Top performing wells by IRR:")
top_wells = econ.indicators.nlargest(5, 'IRR')
print(top_wells[['UID', 'IRR', 'DCF', 'PAYOUT']])

Performance Considerations

• Large Datasets: The module uses vectorized operations for optimal performance
• Memory Usage: For very large datasets, consider processing in batches
• Three-Phase Mode: Requires more computation time but provides independent phase analysis
• Economic Analysis: Cashflow generation is optimized for large well portfolios
• Progress Tracking: Use verbose=True for progress bars on large datasets

Validation

The package includes comprehensive validation tests:

# Run validation tests
python tests/validate_three_phase.py
python tests/dca_test.py
python tests/test_econ.py

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.