pyrestoolbox 3.3.0__tar.gz → 3.5.0__tar.gz

{pyrestoolbox-3.3.0 → pyrestoolbox-3.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyrestoolbox
-Version: 3.3.0
+Version: 3.5.0
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Rust
 Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)

{pyrestoolbox-3.3.0 → pyrestoolbox-3.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "pyrestoolbox"
-version = "3.3.0"
+version = "3.5.0"
 description = "pyResToolbox - A collection of Reservoir Engineering Utilities"
 license = {text = "GPL-3.0-or-later"}
 authors = [{name = "Mark W. Burgoyne", email = "mark.w.burgoyne@gmail.com"}]

{pyrestoolbox-3.3.0 → pyrestoolbox-3.5.0}/pyrestoolbox/brine/_lib_vle_engine.py

@@ -2106,15 +2106,21 @@ class SWMultiComponentFlash:
         # specialised ks models (Dubessy CO2, Akinfiev H2S, Li HC,
         # Mao-Duan N2, Duan-Sun CO2) are applied in self.calc_gamma()
         # on the Python side.
-        if _RUST_AVAILABLE:
+        #
+        # Restricted to framework='proposed': the Rust flash hardcodes the
+        # MC-3 water alpha and the proposed-framework kij_AQ. The 'dropin'
+        # and 'sw_original' frameworks use a salinity-dependent Soreide water
+        # alpha and different kij_AQ correlations that Rust does not implement,
+        # so they must take the Python path to avoid a silent downgrade.
+        if _RUST_AVAILABLE and self.framework == 'proposed':
             try:
                 gamma_arr = np.asarray(gamma, dtype=float) if gamma is not None \
                     else np.ones(self.nc)
-                V, x_r, y_r = _rust.flash_tp_rust(
+                V, x_r, y_r, conv_r = _rust.flash_tp_rust(
                     T_K, P_Pa, z.tolist(), list(self.names),
                     0.0, mode, gamma_arr.tolist(),
                 )
-                return V, np.array(x_r), np.array(y_r), True
+                return V, np.array(x_r), np.array(y_r), conv_r
             except (ImportError, AttributeError):
                 pass
 
@@ -2269,8 +2275,12 @@ class SWMultiComponentFlash:
             salinity_method = 'explicit'
 
         # Rust acceleration path: compute gamma in Python (correct ks models),
-        # then use Rust flash_tp for the two flashes.
-        if _RUST_AVAILABLE and salinity_method == 'gamma_phi':
+        # then use Rust flash_tp for the two flashes. Restricted to
+        # framework='proposed' — Rust only implements the proposed-framework
+        # water alpha (MC-3) and kij_AQ; 'dropin'/'sw_original' would be
+        # silently downgraded to 'proposed', so they take the Python path.
+        if (_RUST_AVAILABLE and salinity_method == 'gamma_phi'
+                and self.framework == 'proposed'):
             try:
                 gamma_aq = None
                 if self.salinity > 0:
@@ -2281,11 +2291,11 @@ class SWMultiComponentFlash:
                     else [1.0] * self.nc
                 names_list = list(self.names)
 
-                V_aq, x_aq_r, y_aq_r = _rust.flash_tp_rust(
+                V_aq, x_aq_r, y_aq_r, conv_aq = _rust.flash_tp_rust(
                     T_K, P_Pa, z.tolist(), names_list,
                     self.salinity, 'AQ', gamma_list,
                 )
-                V_na, x_na_r, y_na_r = _rust.flash_tp_rust(
+                V_na, x_na_r, y_na_r, conv_na = _rust.flash_tp_rust(
                     T_K, P_Pa, z.tolist(), names_list,
                     self.salinity, 'NA', [1.0] * self.nc,
                 )
@@ -2296,7 +2306,7 @@ class SWMultiComponentFlash:
                 result = {
                     'x_aq': x_aq, 'y_na': y_na, 'K_true': K_true,
                     'V_aq': V_aq, 'V_na': V_na,
-                    'converged_aq': True, 'converged_na': True,
+                    'converged_aq': conv_aq, 'converged_na': conv_na,
                     'component_names': self.names,
                     'salinity_method': salinity_method,
                     'vlle_warning': False,

{pyrestoolbox-3.3.0 → pyrestoolbox-3.5.0}/pyrestoolbox/brine/brine.py

@@ -37,6 +37,8 @@ __all__ = [
     'brine_props', 'CO2_Brine_Mixture', 'SoreideWhitson', 'make_pvtw_table',
 ]
 
+import warnings
+
 import numpy as np
 import numpy.typing as npt
 import pandas as pd
@@ -133,6 +135,8 @@ def brine_props(p: float = None, degf: float = None, wt: float = None, ch4_sat:
         p = pres
     if degf is None and temp is not None:
         degf = temp
+    if wt is not None and ppm is not None:
+        raise ValueError("Supply either wt or ppm, not both.")
     if wt is None:
         wt = ppm / 10000 if ppm is not None else 0
     if p is None or degf is None:
@@ -467,19 +471,21 @@ class CO2_Brine_Mixture():
                 >> array([0.02431245, 0.95743175])
                 
             Usage example for 175 Bara x 85 degC and 0% NaCl brine:
-                mix = brine.CO2_Brine_Mixture(pres = 175, temp = 85)
+                mix = brine.CO2_Brine_Mixture(pres = 175, temp = 85, metric = True)
                 mix.Rs  # Returns sm3 dissolved CO2 / sm3 Brine
                 >> 24.742923469934272
                 
            
     """
-    def __init__(self, pres=None, temp=None, ppm=None, metric=True, cw_sat=False,
+    def __init__(self, pres=None, temp=None, ppm=None, metric=False, cw_sat=False,
                  *, p=None, degf=None, wt=None):
         # Resolve parameter aliases (p/degf/wt -> pres/temp/ppm)
         if pres is None and p is not None:
             pres = p
         if temp is None and degf is not None:
             temp = degf
+        if ppm is not None and wt is not None:
+            raise ValueError("Supply either ppm or wt, not both.")
         if ppm is None:
             ppm = wt * 10000 if wt is not None else 0
         if pres is None or temp is None:
@@ -961,9 +967,10 @@ class CO2_Brine_Mixture():
         """
         if _RUST_AVAILABLE:
             try:
-                xco2, yco2, yh2o, rhogas, gasz = _rust.co2_brine_solubility_rust(
+                xco2, yco2, yh2o, rhogas, gasz, conv = _rust.co2_brine_solubility_rust(
                     self.pBar, self.degC, self.ppm
                 )
+                self.converged = conv
                 self.x = np.array([xco2, 1.0 - xco2 - (self.xSalt if self.xSalt else 0.0)])
                 self.y = np.array([yco2, yh2o])
                 self.rhoGas = rhogas
@@ -1436,8 +1443,15 @@ class SoreideWhitson:
             y_N2: Mole fraction N2 in dry gas (default 0)
             y_H2: Mole fraction H2 in dry gas (default 0)
             sg: Gas specific gravity — used to estimate HC split among C1-C4 (default 0.65)
-            metric: Boolean for units (True=metric, False=oilfield). Default True.
+            metric: Boolean for units (True=metric, False=oilfield). Default False.
             cw_sat: If True, also calculate saturated compressibility (default False)
+            framework: VLE framework. 'proposed' (default, Soreide-Whitson 1992 re-fit),
+                'sw_original' (original 1992 published), or 'dropin' (fitted to PR-EOS with
+                brine-aware water alpha). Affects kij and ks correlations.
+            salinity_method: How salinity enters the flash. 'gamma_phi' (default, Sechenov
+                salting-out via activity coefficient), 'embedded' (salinity inside kij —
+                only for 'dropin'/'sw_original'), 'explicit' (brine treated as a component),
+                'sechenov' (legacy alias for gamma_phi), or 'auto' (pick per-gas defaults).
 
         Returns object with following calculated properties:
             .x          : Dict of dissolved gas mole fractions, e.g. {'CO2': 0.024, 'CH4': 0.0015}
@@ -1462,7 +1476,7 @@ class SoreideWhitson:
             mix.Rs  # Returns per-gas Rs dict, e.g. {'CO2': 15.2}
 
             # Mixed gas, metric units
-            mix = brine.SoreideWhitson(pres=200, temp=80, ppm=10000, y_CO2=0.1, y_H2S=0.05, sg=0.7)
+            mix = brine.SoreideWhitson(pres=200, temp=80, ppm=10000, y_CO2=0.1, y_H2S=0.05, sg=0.7, metric=True)
             mix.bDen  # Returns [gas-saturated, gas-free, freshwater] densities
 
         References:
@@ -1482,13 +1496,20 @@ class SoreideWhitson:
             Murphy, W.R. and Gaines, T.M. (1974), J. Chem. Eng. Data 19(4), 359-362.
     """
 
+    _VALID_FRAMEWORKS = ('proposed', 'sw_original', 'dropin')
+    _VALID_SALINITY_METHODS = ('gamma_phi', 'embedded', 'explicit', 'auto', 'sechenov')
+
     def __init__(self, pres=None, temp=None, ppm=None, y_CO2=0, y_H2S=0, y_N2=0, y_H2=0,
-                 sg=0.65, metric=True, cw_sat=False, *, p=None, degf=None, wt=None):
+                 sg=0.65, metric=False, cw_sat=False,
+                 framework='proposed', salinity_method='gamma_phi',
+                 *, p=None, degf=None, wt=None):
         # Resolve parameter aliases (p/degf/wt -> pres/temp/ppm)
         if pres is None and p is not None:
             pres = p
         if temp is None and degf is not None:
             temp = degf
+        if ppm is not None and wt is not None:
+            raise ValueError("Supply either ppm or wt, not both.")
         if ppm is None:
             ppm = wt * 10000 if wt is not None else 0
         if pres is None or temp is None:
@@ -1497,6 +1518,22 @@ class SoreideWhitson:
             raise ValueError(f"ppm must be non-negative, got {ppm}")
         if ppm >= 1e6:
             raise ValueError(f"ppm must be less than 1,000,000, got {ppm}")
+        if framework not in self._VALID_FRAMEWORKS:
+            raise ValueError(
+                f"Invalid framework: {framework!r}. Valid options: {list(self._VALID_FRAMEWORKS)}"
+            )
+        if salinity_method not in self._VALID_SALINITY_METHODS:
+            raise ValueError(
+                f"Invalid salinity_method: {salinity_method!r}. Valid options: {list(self._VALID_SALINITY_METHODS)}"
+            )
+        if framework == 'proposed' and salinity_method == 'embedded':
+            warnings.warn(
+                "framework='proposed' does not define embedded-salinity kij; engine will "
+                "fall back to the 'gamma_phi' behaviour.",
+                stacklevel=2,
+            )
+        self.framework = framework
+        self.salinity_method = salinity_method
         # Validate pressure and temperature (convert to oilfield units for validation)
         _p_val = pres if not metric else pres * BAR2PSI
         _t_val = temp if not metric else temp * 1.8 + 32
@@ -1742,8 +1779,8 @@ class SoreideWhitson:
             y_H2S=self.gas_comp.get('H2S', 0),
             y_H2=self.gas_comp.get('H2', 0),
             method='flash',
-            salinity_method='gamma_phi',
-            framework='proposed',
+            salinity_method=self.salinity_method,
+            framework=self.framework,
         )
 
         self.x = x_gas
@@ -1903,8 +1940,10 @@ class SoreideWhitson:
                 gas_ply = _VLE_TO_PLYASUNOV.get(gas_vle, gas_vle.upper())
                 vphi_eff_p1 += yi * _plyasunov_V_phi(gas_ply, tKel, Mpa_p1)
 
-            numerator_p1 = 1.0 + self.x_total * mw_eff / (MWWAT * x1)
-            denom_p1 = self.x_total * vphi_eff_p1 / (MWWAT * x1) + 1.0 / rho_brine_p1_gcc
+            # Garcia Eq. 18 at P+1, same algebraically reformulated (non-singular)
+            # form as Step 3 — multiply top/bot through by M1*x1.
+            numerator_p1 = MWWAT * x1 + self.x_total * mw_eff
+            denom_p1 = self.x_total * vphi_eff_p1 + MWWAT * x1 / rho_brine_p1_gcc
             rho_p1_gcc = numerator_p1 / denom_p1
         else:
             rho_p1_gcc = rho_brine_p1_gcc

{pyrestoolbox-3.3.0 → pyrestoolbox-3.5.0}/pyrestoolbox/dca/dca.py

@@ -51,7 +51,8 @@ __all__ = [
 
 import numpy as np
 from dataclasses import dataclass, field
-from typing import Optional
+from typing import Optional, Union
+from numpy.typing import ArrayLike
 
 from pyrestoolbox.shared_fns import convert_to_numpy, process_output, ransac_linreg
 from pyrestoolbox._accelerator import RUST_AVAILABLE as _RUST_AVAILABLE
@@ -59,6 +60,66 @@ if _RUST_AVAILABLE:
     from pyrestoolbox import _native as _rust
 
 
+# ---------------------------------------------------------------------------
+# Named constants — extracted from inline magic numbers per CLAUDE.md rules.
+# ---------------------------------------------------------------------------
+
+# Arps hyperbolic b-grid search (Arps 1945; b physically in (0, 1))
+# 0.05-0.95 avoids exponential (b=0) / harmonic (b=1) degeneracies.
+_B_GRID_MIN = 0.05
+_B_GRID_MAX = 0.96
+_B_GRID_STEP = 0.01
+
+# Duong (2011) cumulative integration grid
+_DUONG_TRAP_LB = 0.001      # Lower trap bound to avoid t=0 singularity
+_DUONG_GRID_MIN = 500       # Minimum trap grid points per integration
+_DUONG_GRID_DENSITY = 10    # Additional points per unit t
+
+# Duong curve_fit bounds and initial guess (Duong 2011, Eq. 5)
+_DUONG_BOUNDS_LO = (0.0, 0.01, 1.001)
+_DUONG_BOUNDS_HI_QI_FACTOR = 5.0   # Upper qi bound = first q * factor
+_DUONG_BOUNDS_HI_A = 10.0
+_DUONG_BOUNDS_HI_M = 3.0
+_DUONG_P0_A = 1.0              # Initial guess a
+_DUONG_P0_M = 1.2              # Initial guess m
+
+# scipy.curve_fit iteration cap (covers Duong + logistic fits)
+_CURVE_FIT_MAXFEV = 5000
+
+# Numerical floors / near-zero guards
+_HYPER_INNER_FLOOR = 1e-10     # Floor for (1 - di*Np*exp/qi)^(1/exp) argument
+_ZERO_DIV_EPS = 1e-30          # General division-by-zero guard
+
+# Logistic ratio curve_fit (unconventional GOR/WOR trending)
+_LOGISTIC_P0_RMAX_INIT = 1.5   # Initial Rmax guess = max(ratio) * factor
+_LOGISTIC_P0_TC = 0.01         # Initial carryover constant
+_LOGISTIC_P0_ALPHA = 10.0      # Initial curvature
+_LOGISTIC_BOUNDS_LO = (1e-8, 1e-3)  # Lower (tc, alpha) bounds
+_LOGISTIC_BOUNDS_RMAX_FACTOR = 5.0  # Upper Rmax = max(ratio) * factor
+_LOGISTIC_BOUNDS_HI = 1e6      # Upper tc / alpha bound
+
+
+def _build_decline_result(method, q_obs, q_pred, **params):
+    """DRY helper: compute R-squared + residuals, return a DeclineResult.
+
+    Parameters
+    ----------
+    method : str
+    q_obs, q_pred : np.ndarray  (observed and predicted rates)
+    **params : scalar DeclineResult fields (qi, di, b, a, m)
+    """
+    residuals = q_obs - q_pred
+    ss_res = np.sum(residuals ** 2)
+    ss_tot = np.sum((q_obs - np.mean(q_obs)) ** 2)
+    r2 = 1.0 - ss_res / ss_tot if ss_tot > 0 else 0.0
+    return DeclineResult(
+        method=method,
+        r_squared=r2,
+        residuals=residuals,
+        **params,
+    )
+
+
 def _fmt_array(a, name):
     if a is None:
         return f"{name}=None"
@@ -189,7 +250,7 @@ class RatioResult:
         )
 
 
-def arps_rate(qi, di, b, t):
+def arps_rate(qi: float, di: float, b: float, t: ArrayLike) -> Union[float, np.ndarray]:
     """Arps decline rate.
 
     Parameters
@@ -226,7 +287,7 @@ def arps_rate(qi, di, b, t):
     return process_output(q, is_list)
 
 
-def arps_cum(qi, di, b, t):
+def arps_cum(qi: float, di: float, b: float, t: ArrayLike) -> Union[float, np.ndarray]:
     """Arps cumulative production.
 
     Parameters
@@ -263,7 +324,7 @@ def arps_cum(qi, di, b, t):
     return process_output(Qcum, is_list)
 
 
-def duong_rate(qi, a, m, t):
+def duong_rate(qi: float, a: float, m: float, t: ArrayLike) -> Union[float, np.ndarray]:
     """Duong decline rate for unconventional reservoirs.
 
     q(t) = qi * t^(-m) * exp(a/(1-m) * (t^(1-m) - 1))
@@ -296,7 +357,7 @@ def duong_rate(qi, a, m, t):
     return process_output(q, is_list)
 
 
-def duong_cum(qi, a, m, t):
+def duong_cum(qi: float, a: float, m: float, t: ArrayLike) -> Union[float, np.ndarray]:
     """Duong cumulative production via trapezoidal integration.
 
     Parameters
@@ -328,15 +389,15 @@ def duong_cum(qi, a, m, t):
     # integrates over a descending axis and returns negative cumulative.
     results = np.zeros_like(t, dtype=float)
     for i, ti in enumerate(t):
-        lower = min(0.001, ti * 0.001)
-        t_fine = np.linspace(lower, ti, max(500, int(ti * 10)))
+        lower = min(_DUONG_TRAP_LB, ti * _DUONG_TRAP_LB)
+        t_fine = np.linspace(lower, ti, max(_DUONG_GRID_MIN, int(ti * _DUONG_GRID_DENSITY)))
         q_fine = qi * t_fine ** (-m) * np.exp(a / (1.0 - m) * (t_fine ** (1.0 - m) - 1.0))
         results[i] = np.trapezoid(q_fine, t_fine)
 
     return process_output(results, is_list)
 
 
-def eur(qi, di, b, q_min):
+def eur(qi: float, di: float, b: float, q_min: float) -> float:
     """Estimated ultimate recovery for Arps decline.
 
     Parameters
@@ -382,13 +443,7 @@ def _fit_exponential(t, q):
     if di <= 0:
         return None
     q_pred = qi * np.exp(-di * t)
-    ss_res = np.sum((q - q_pred) ** 2)
-    ss_tot = np.sum((q - np.mean(q)) ** 2)
-    r2 = 1.0 - ss_res / ss_tot if ss_tot > 0 else 0.0
-    return DeclineResult(
-        method='exponential', qi=qi, di=di, b=0.0,
-        r_squared=r2, residuals=q - q_pred,
-    )
+    return _build_decline_result('exponential', q, q_pred, qi=qi, di=di, b=0.0)
 
 
 def _fit_harmonic(t, q):
@@ -403,13 +458,7 @@ def _fit_harmonic(t, q):
     if di <= 0:
         return None
     q_pred = qi / (1.0 + di * t)
-    ss_res = np.sum((q - q_pred) ** 2)
-    ss_tot = np.sum((q - np.mean(q)) ** 2)
-    r2 = 1.0 - ss_res / ss_tot if ss_tot > 0 else 0.0
-    return DeclineResult(
-        method='harmonic', qi=qi, di=di, b=1.0,
-        r_squared=r2, residuals=q - q_pred,
-    )
+    return _build_decline_result('harmonic', q, q_pred, qi=qi, di=di, b=1.0)
 
 
 def _fit_hyperbolic(t, q):
@@ -423,18 +472,14 @@ def _fit_hyperbolic(t, q):
         try:
             qi, di, b, r2 = _rust.fit_hyperbolic_rust(t.tolist(), q.tolist())
             q_pred = qi / (1.0 + b * di * t) ** (1.0 / b)
-            return DeclineResult(
-                method='hyperbolic', qi=qi, di=di, b=b,
-                r_squared=r2, residuals=q - q_pred,
-            )
+            return _build_decline_result('hyperbolic', q, q_pred, qi=qi, di=di, b=b)
         except (ImportError, AttributeError):
             pass
 
     best_r2 = -np.inf
     best_result = None
-    ss_tot = np.sum((q - np.mean(q)) ** 2)
 
-    for b_trial in np.arange(0.05, 0.96, 0.01):
+    for b_trial in np.arange(_B_GRID_MIN, _B_GRID_MAX, _B_GRID_STEP):
         # Transform: Y = q^(-b) is linear in t
         Y = q ** (-b_trial)
         slope, intercept, _ = ransac_linreg(t, Y)
@@ -451,15 +496,10 @@ def _fit_hyperbolic(t, q):
 
         # Compute R-squared in original rate space
         q_pred = qi / (1.0 + b_trial * di * t) ** (1.0 / b_trial)
-        ss_res = np.sum((q - q_pred) ** 2)
-        r2 = 1.0 - ss_res / ss_tot if ss_tot > 0 else 0.0
-
-        if r2 > best_r2:
-            best_r2 = r2
-            best_result = DeclineResult(
-                method='hyperbolic', qi=qi, di=di, b=b_trial,
-                r_squared=r2, residuals=q - q_pred,
-            )
+        result = _build_decline_result('hyperbolic', q, q_pred, qi=qi, di=di, b=b_trial)
+        if result.r_squared > best_r2:
+            best_r2 = result.r_squared
+            best_result = result
 
     return best_result
 
@@ -478,20 +518,19 @@ def _fit_duong(t, q):
     t_f, q_f = t[mask], q[mask]
 
     try:
-        popt, _ = curve_fit(duong_func, t_f, q_f, p0=[q_f[0], 1.0, 1.2],
-                            bounds=([0, 0.01, 1.001], [q_f[0] * 5, 10.0, 3.0]),
-                            maxfev=5000)
-        qi, a, m = popt
-        q_pred_full = np.full_like(q, np.nan, dtype=float)
-        q_pred_full[mask] = duong_func(t_f, qi, a, m)
-        q_pred_valid = q_pred_full[mask]
-        ss_res = np.sum((q_f - q_pred_valid) ** 2)
-        ss_tot = np.sum((q_f - np.mean(q_f)) ** 2)
-        r2 = 1.0 - ss_res / ss_tot if ss_tot > 0 else 0.0
-        return DeclineResult(
-            method='duong', qi=qi, a=a, m=m,
-            r_squared=r2, residuals=q_f - q_pred_valid,
+        popt, _ = curve_fit(
+            duong_func, t_f, q_f,
+            p0=[q_f[0], _DUONG_P0_A, _DUONG_P0_M],
+            bounds=(
+                list(_DUONG_BOUNDS_LO),
+                [q_f[0] * _DUONG_BOUNDS_HI_QI_FACTOR,
+                 _DUONG_BOUNDS_HI_A, _DUONG_BOUNDS_HI_M],
+            ),
+            maxfev=_CURVE_FIT_MAXFEV,
         )
+        qi, a, m = popt
+        q_pred_valid = duong_func(t_f, qi, a, m)
+        return _build_decline_result('duong', q_f, q_pred_valid, qi=qi, a=a, m=m)
     except (RuntimeError, ValueError):
         return None
 
@@ -507,13 +546,7 @@ def _fit_exponential_cum(Np, q):
     if di <= 0 or qi <= 0:
         return None
     q_pred = qi - di * Np
-    ss_res = np.sum((q - q_pred) ** 2)
-    ss_tot = np.sum((q - np.mean(q)) ** 2)
-    r2 = 1.0 - ss_res / ss_tot if ss_tot > 0 else 0.0
-    return DeclineResult(
-        method='exponential', qi=qi, di=di, b=0.0,
-        r_squared=r2, residuals=q - q_pred,
-    )
+    return _build_decline_result('exponential', q, q_pred, qi=qi, di=di, b=0.0)
 
 
 def _fit_harmonic_cum(Np, q):
@@ -529,13 +562,7 @@ def _fit_harmonic_cum(Np, q):
     if di <= 0 or qi <= 0:
         return None
     q_pred = qi * np.exp(-di / qi * Np)
-    ss_res = np.sum((q - q_pred) ** 2)
-    ss_tot = np.sum((q - np.mean(q)) ** 2)
-    r2 = 1.0 - ss_res / ss_tot if ss_tot > 0 else 0.0
-    return DeclineResult(
-        method='harmonic', qi=qi, di=di, b=1.0,
-        r_squared=r2, residuals=q - q_pred,
-    )
+    return _build_decline_result('harmonic', q, q_pred, qi=qi, di=di, b=1.0)
 
 
 def _fit_hyperbolic_cum(Np, q):
@@ -550,20 +577,16 @@ def _fit_hyperbolic_cum(Np, q):
         try:
             qi, di, b, r2 = _rust.fit_hyperbolic_cum_rust(Np.tolist(), q.tolist())
             exp = 1.0 - b
-            inner = np.maximum(1.0 - exp * di * Np / qi, 1e-10)
+            inner = np.maximum(1.0 - exp * di * Np / qi, _HYPER_INNER_FLOOR)
             q_pred = qi * inner ** (1.0 / exp)
-            return DeclineResult(
-                method='hyperbolic', qi=qi, di=di, b=b,
-                r_squared=r2, residuals=q - q_pred,
-            )
+            return _build_decline_result('hyperbolic', q, q_pred, qi=qi, di=di, b=b)
         except (ImportError, AttributeError):
             pass
 
     best_r2 = -np.inf
     best_result = None
-    ss_tot = np.sum((q - np.mean(q)) ** 2)
 
-    for b_trial in np.arange(0.05, 0.96, 0.01):
+    for b_trial in np.arange(_B_GRID_MIN, _B_GRID_MAX, _B_GRID_STEP):
         exp = 1.0 - b_trial
         # Transform: Np = A + B * q^(1-b)
         X = q ** exp
@@ -572,7 +595,7 @@ def _fit_hyperbolic_cum(Np, q):
         # A = intercept = qi / ((1-b)*di)
         # B = slope = -qi^b / ((1-b)*di)
         # B/A = -qi^b / qi = -qi^(b-1) = -1/qi^(1-b)
-        if abs(slope) < 1e-30 or abs(intercept) < 1e-30:
+        if abs(slope) < _ZERO_DIV_EPS or abs(intercept) < _ZERO_DIV_EPS:
             continue
         ratio = slope / intercept  # = -1/qi^(1-b)
         if ratio >= 0:
@@ -588,23 +611,20 @@ def _fit_hyperbolic_cum(Np, q):
             continue
 
         # Compute R-squared in original rate space
-        inner = 1.0 - exp * di * Np / qi
-        inner = np.maximum(inner, 1e-10)
+        inner = np.maximum(1.0 - exp * di * Np / qi, _HYPER_INNER_FLOOR)
         q_pred = qi * inner ** (1.0 / exp)
-        ss_res = np.sum((q - q_pred) ** 2)
-        r2 = 1.0 - ss_res / ss_tot if ss_tot > 0 else 0.0
-
-        if r2 > best_r2:
-            best_r2 = r2
-            best_result = DeclineResult(
-                method='hyperbolic', qi=qi, di=di, b=b_trial,
-                r_squared=r2, residuals=q - q_pred,
-            )
+        result = _build_decline_result('hyperbolic', q, q_pred, qi=qi, di=di, b=b_trial)
+        if result.r_squared > best_r2:
+            best_r2 = result.r_squared
+            best_result = result
 
     return best_result
 
 
-def fit_decline_cum(Np, q, method='best', t_calendar=None, Np_start=None, Np_end=None):
+def fit_decline_cum(Np: ArrayLike, q: ArrayLike, method: str = 'best',
+                    t_calendar: Optional[ArrayLike] = None,
+                    Np_start: Optional[float] = None,
+                    Np_end: Optional[float] = None) -> 'DeclineResult':
     """Fit a decline model to rate-vs-cumulative data.
 
     Eliminates time from the Arps equations to fit q as a function of Np.
@@ -708,7 +728,9 @@ def fit_decline_cum(Np, q, method='best', t_calendar=None, Np_start=None, Np_end
     return best
 
 
-def fit_decline(t, q, method='best', t_start=None, t_end=None):
+def fit_decline(t: ArrayLike, q: ArrayLike, method: str = 'best',
+                t_start: Optional[float] = None,
+                t_end: Optional[float] = None) -> 'DeclineResult':
     """Fit a decline model to production data.
 
     Parameters
@@ -832,11 +854,17 @@ def _fit_ratio_logistic(x, ratio):
         return Rmax / (1.0 + c * np.exp(-b * x))
 
     try:
-        Rmax_guess = np.max(ratio) * 1.5
-        popt, _ = curve_fit(logistic_func, x, ratio,
-                            p0=[Rmax_guess, 0.01, 10.0],
-                            bounds=([0, 1e-8, 1e-3], [Rmax_guess * 5, 10.0, 1e6]),
-                            maxfev=5000)
+        Rmax_guess = np.max(ratio) * _LOGISTIC_P0_RMAX_INIT
+        popt, _ = curve_fit(
+            logistic_func, x, ratio,
+            p0=[Rmax_guess, _LOGISTIC_P0_TC, _LOGISTIC_P0_ALPHA],
+            bounds=(
+                [0.0, _LOGISTIC_BOUNDS_LO[0], _LOGISTIC_BOUNDS_LO[1]],
+                [Rmax_guess * _LOGISTIC_BOUNDS_RMAX_FACTOR,
+                 _LOGISTIC_BOUNDS_HI, _LOGISTIC_BOUNDS_HI],
+            ),
+            maxfev=_CURVE_FIT_MAXFEV,
+        )
         Rmax, b, c = popt
         r_pred = logistic_func(x, Rmax, b, c)
         ss_res = np.sum((ratio - r_pred) ** 2)
@@ -850,7 +878,8 @@ def _fit_ratio_logistic(x, ratio):
         return None
 
 
-def fit_ratio(x, ratio, method='best', domain='cum'):
+def fit_ratio(x: ArrayLike, ratio: ArrayLike,
+              method: str = 'best', domain: str = 'cum') -> 'RatioResult':
     """Fit a ratio model (e.g. GOR, WOR) to data.
 
     Parameters
@@ -904,7 +933,7 @@ def fit_ratio(x, ratio, method='best', domain='cum'):
         return result
 
 
-def ratio_forecast(result, x):
+def ratio_forecast(result: 'RatioResult', x: ArrayLike) -> np.ndarray:
     """Evaluate a fitted ratio model at given x values.
 
     Parameters
@@ -935,7 +964,9 @@ def ratio_forecast(result, x):
     return process_output(r, is_list)
 
 
-def forecast(result, t_end, dt=1.0, q_min=0.0, uptime=1.0, ratios=None):
+def forecast(result: 'DeclineResult', t_end: float, dt: float = 1.0,
+             q_min: float = 0.0, uptime: float = 1.0,
+             ratios: Optional[dict] = None) -> 'ForecastResult':
     """Generate a rate and cumulative forecast from a fitted decline model.
 
     Parameters