This guide walks through a full ResSmith workflow using a single well. The example uses a synthetic decline series. The goal is clarity and structure.

Overview

ResSmith provides a comprehensive toolkit for reservoir engineering analysis, from single-well decline curve analysis to portfolio-level forecasting and economics. This guide demonstrates the core workflow: production data → decline model fitting → forecast → economics.

Production Data Preparation

We begin with a pandas DataFrame that represents monthly oil production.

import numpy as np
import pandas as pd

idx = pd.date_range("2019-01-01", periods=48, freq="ME")
rate = 800 * (1 + 0.02 * idx.month) ** -1
rate = rate + np.random.normal(0, 20, size=len(rate))

# Default decline fitting expects an ``oil`` rate column (or pass ``phase`` / column mapping).
df = pd.DataFrame({"oil": rate}, index=idx)

ResSmith validates temporal inputs using shared typing from Timesmith (optional).

from timesmith.typing.validators import assert_series_like

assert_series_like(df["oil"])

We fit a decline model. fit_forecast returns (forecast, fitted_params).

from ressmith.workflows import fit_forecast

forecast, params = fit_forecast(
    df,
    model_name="arps_hyperbolic",
    horizon=24,
)

The result contains a forecasted rate series and model metadata.

print(forecast.yhat.tail())
print(params)

We now evaluate economics. EconSpec uses per-period operating expense in the current cashflow helper (not $/bbl); adjust to your forecast step.

from ressmith.workflows import evaluate_economics
from ressmith.objects import EconSpec

econ = EconSpec(
    price_assumptions={"oil": 70.0},
    opex=400.0,
    capex=0.0,
    discount_rate=0.1,
)

econ_result = evaluate_economics(forecast, econ)

The output includes cashflows and value metrics.

print(econ_result.npv)
print(econ_result.irr)
print(econ_result.cashflows.head())

Model Selection

ResSmith supports multiple decline models. The choice depends on your reservoir:

  • ARPS Hyperbolic (arps_hyperbolic): Most common for oil and gas wells. Use when decline rate decreases over time (b-factor > 0).

  • ARPS Exponential (arps_exponential): Use for wells with constant decline rate (b = 0).

  • ARPS Harmonic (arps_harmonic): Use when b = 1 (rare in practice).

  • Power Law (power_law): Good for unconventional plays with complex decline behavior.

  • Duong (duong): Designed for tight gas and shale wells.

When to use each model:

  • Early-time data (< 12 months): Use Power Law or Duong models

  • Mature wells (> 24 months): ARPS Hyperbolic is usually appropriate

  • Unconventional plays: Try ensemble_forecast() with multiple models

Common Workflows

Comparing Multiple Models

from ressmith.workflows import compare_models

comparison = compare_models(
    data=df,
    model_names=['arps_hyperbolic', 'power_law', 'duong'],
    horizon=36
)
print(comparison.sort_values('r_squared', ascending=False))

Probabilistic Forecasting (P10/P50/P90)

from ressmith.workflows import probabilistic_forecast

prob_result = probabilistic_forecast(
    data=df,
    model_name='arps_hyperbolic',
    horizon=36,
    n_samples=1000
)
print(f"P50 EUR: {prob_result['p50'].sum():.0f} bbl")
print(f"P10 EUR: {prob_result['p10'].sum():.0f} bbl")
print(f"P90 EUR: {prob_result['p90'].sum():.0f} bbl")

Portfolio Analysis

Each well’s frame should match the fit workflow: DatetimeIndex and an oil column (unless you pass a column mapping via fit_forecast / portfolio kwargs).

from ressmith.workflows import analyze_portfolio

well_data = {
    "well_1": df,
    "well_2": df.assign(oil=df["oil"] * 0.95),
    "well_3": df.assign(oil=df["oil"] * 1.05),
}
portfolio = analyze_portfolio(
    well_data,
    model_name="arps_hyperbolic",
    econ_spec=econ,
)
print(portfolio.sort_values("npv", ascending=False))

Best Practices

  1. Data Quality: Ensure production data is clean (no negative rates, valid dates)

  2. Model Selection: Start with ARPS Hyperbolic, try ensemble for uncertainty

  3. Forecast Horizon: Use 2-3x historical data length for forecasts

  4. Economics: Always use probabilistic forecasting for reserves estimation

  5. Validation: Use walk_forward_backtest() to validate model performance

Next Steps

  • See examples/ directory for more complex workflows

  • Check docs/architecture.md for architecture details

  • Review API documentation for advanced features

This is the full ResSmith loop. Rates become forecasts. Forecasts become cashflow. Each step stays explicit and testable.