pyrestoolbox 3.3.0__tar.gz → 3.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyrestoolbox
-Version: 3.3.0
+Version: 3.4.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.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "pyrestoolbox"
-version = "3.3.0"
+version = "3.4.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.4.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:
@@ -1436,8 +1442,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 +1475,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 +1495,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 +1517,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 +1778,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

{pyrestoolbox-3.3.0 → pyrestoolbox-3.4.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

{pyrestoolbox-3.3.0 → pyrestoolbox-3.4.0}/pyrestoolbox/docs/brine.rst

@@ -14,11 +14,11 @@ Returns tuple of (Bw (rb/stb), Density (sg), viscosity (cP), Compressibility (1/
 Unit System Support
 ----------------------
 
-All three brine models support both oilfield and metric unit systems via a ``metric`` parameter:
+All three brine models default to oilfield units (psia, degF, 1/psi, scf/stb) and accept ``metric=True`` to switch to Eclipse METRIC (barsa, degC, 1/bar, sm3/sm3):
 
-- ``brine_props``: ``metric=False`` (default). When ``metric=True``, pressure is in barsa, temperature is in degC, compressibility is in 1/barsa, and Rsw is in sm3/sm3.
-- ``CO2_Brine_Mixture``: ``metric=True`` (default). When ``metric=False``, pressure is in psia and temperature is in degF.
-- ``SoreideWhitson``: ``metric=True`` (default). When ``metric=False``, pressure is in psia and temperature is in degF.
+- ``brine_props``: ``metric=False`` (default).
+- ``CO2_Brine_Mixture``: ``metric=False`` (default).
+- ``SoreideWhitson``: ``metric=False`` (default).
 
 .. note::
 
@@ -126,7 +126,7 @@ pyrestoolbox.brine.CO2_Brine_Mixture
 
 .. code-block:: python
 
-    CO2_Brine_Mixture(pres, temp, ppm = 0, metric = True) -> class
+    CO2_Brine_Mixture(pres, temp, ppm = 0, metric = False) -> class
 
 .. list-table:: Inputs
    :widths: 10 15 40
@@ -211,7 +211,7 @@ Usage example for 175 Bara x 85 degC and 0% NaCl brine:
 
 .. code-block:: python
 
-    >>> 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.743651168969475
 
@@ -312,7 +312,7 @@ pyrestoolbox.brine.SoreideWhitson
 
 .. code-block:: python
 
-    SoreideWhitson(pres, temp, ppm=0, y_CO2=0, y_H2S=0, y_N2=0, y_H2=0, sg=0.65, metric=True, cw_sat=False) -> class
+    SoreideWhitson(pres, temp, ppm=0, y_CO2=0, y_H2S=0, y_N2=0, y_H2=0, sg=0.65, metric=False, cw_sat=False, framework='proposed', salinity_method='gamma_phi') -> class
 
 Soreide-Whitson (1992) VLE model for multicomponent gas solubility in water/brine, with Garcia/Plyasunov
 density corrections and calibrated viscosity corrections. Supports gas mixtures containing any combination
@@ -377,6 +377,12 @@ based on the gas specific gravity using constrained exponential decay to match t
    * - cw_sat
      - Boolean
      - If True, will also calculate saturated brine compressibility. Default False
+   * - framework
+     - str
+     - VLE framework used by the S&W engine. ``'proposed'`` (default, Soreide-Whitson 1992 re-fit), ``'sw_original'`` (original 1992 published coefficients), or ``'dropin'`` (PR-EOS fitted with brine-aware water alpha). Affects kij and ks correlations.
+   * - salinity_method
+     - str
+     - How salinity enters the flash. ``'gamma_phi'`` (default, Sechenov salting-out via activity coefficient), ``'embedded'`` (salinity inside kij — only compatible with ``'dropin'``/``'sw_original'``), ``'explicit'`` (brine treated as a component in the flash), ``'sechenov'`` (alias for ``gamma_phi``), or ``'auto'`` (pick per-gas default). ``framework='proposed'`` + ``salinity_method='embedded'`` emits a warning and falls back to ``gamma_phi``.
 
 .. list-table:: Returns (SoreideWhitson)
    :widths: 10 15 40

{pyrestoolbox-3.3.0 → pyrestoolbox-3.4.0}/pyrestoolbox/docs/changelist.rst

@@ -1,3 +1,64 @@
+Changelist in 3.4.0:
+
+- **BREAKING — Brine metric default standardization**: ``CO2_Brine_Mixture`` and ``SoreideWhitson`` constructors now default to ``metric=False`` (oilfield units) to match ``brine_props`` and every other pyrestoolbox API. Previously they defaulted to ``metric=True``. Existing callers that relied on the old default must either pass ``metric=True`` explicitly or switch their input units to psia / degF. RST and notebook examples that relied on the default have been updated to pass ``metric=True`` explicitly.
+
+- **nodal.outflow_curve parameter unification**: ``n_rates`` has been renamed to ``n_points`` to match ``ipr_curve`` / ``operating_point``. ``n_rates`` remains accepted as a deprecated alias (takes precedence when both are passed) — existing callers keep working without changes.
+
+- **Type hints on public APIs**: ``nodal`` (fbhp / fthp / outflow_curve / ipr_curve / operating_point), ``oil`` (oil_co/bt return types, OilPVT constructor + methods, oil_rate_radial/linear), and ``dca`` (arps_*, duong_*, eur, fit_*, ratio_forecast, forecast) public signatures now carry type annotations. IDE autocomplete and static analysis now work out of the box for the primary user surface. ``matbal`` / ``simtools`` / ``plyasunov`` type-hint backfill deferred.
+
+- **Rust-vs-Python parity harness**: 63 new parametrized tests added to ``test_rust_acceleration.py``. Coverage:
+
+  - Nodal gas VLP: 4 methods × 6 (THP, rate) points on a vertical well; WG/BB × 2 points on a deviated well (45-degree lower segment).
+  - Nodal oil VLP: 4 methods × 5 (THP, rate) points on a vertical well; WG/BB × 2 points on a deviated well.
+  - SoreideWhitson: pure CO2 across 4 (P, T) × 3 salinity points; sour-gas mix (CO2 + H2S + N2) at 2 points; natural-gas-only at 2 points.
+
+  Purpose is prophylactic — catches future one-sided edits between Python and Rust. Tolerance is ``RTOL_MEDIUM = 1e-4``.
+
+- **Rust HB-oil VLP bugfix (correctness)**. Three dimensional bugs in ``src/vlp/segment_oil.rs`` (HB oil only — WG/GRAY/BB oil were coded correctly):
+
+  1. ``min_l`` formula (``rho_g * 62.37 / (rho_g * 62.37 + lsg * 62.37)`` simplified to ``rho_g_lbft3 / (rho_g_lbft3 + lsg_SG)``) mixed lb/cuft with dimensionless SG. Forced ~35% minimum liquid holdup at low rate when Python computed ~2%. Dominant contributor to the divergence.
+  2. ``rho_avg`` averaged gas vs stock-tank oil density, not the oil+water mixture density that includes live-oil McCain correction and water cut.
+  3. ``ul`` superficial liquid velocity used stock-tank volumetric flow (``ql * 5.615 / 86400 / area``) instead of reservoir-conditions volumetric (``mflow_l / rho_l / area``). Missed the live-oil expansion / water-cut weighting.
+
+  Combined effect was up to ~75% over-prediction of BHP for HB oil wells at low rate / low THP. Python path was always correct; bug was isolated to the Rust accelerator. The ``hb_holdup`` helper signature changed from taking ``lsg`` (implicit ``62.4 * lsg`` internally) to taking ``rho_l`` directly; gas-segment callers updated to pass ``62.4 * lsg_loc`` to preserve prior behaviour. Parity harness drift reduced from 75% to <0.1% on the affected grid.
+
+- **Nodal ``operating_point`` non-monotonic VLP handling**. HB oil VLP curves can be non-monotonic at very low rate (spurious near-shut-in high BHP from holdup correlations). The previous bisection bracketed ``[min_rate, AOF]`` and failed when both endpoints had the same sign despite a crossing existing in between. Replaced with a scan-then-bisect: sample 25 rates, locate all sign changes in the error function, and bisect in the highest-rate bracket — the physical operating point. Sets ``converged=False`` if no sign change is found.
+
+- **HB oil doc-example values updated**. Three expected values changed due to the Rust HB-oil bugfix (Python values unchanged, Rust values now match Python):
+
+  - ``fbhp(thp=200, ..., vlpmethod='HB', well_type='oil', qt_stbpd=2000, ...)``: 2271.72 psi → 1771.47 psi
+  - ``fbhp`` with ``oil_pvt=opvt``: 2273.72 psi → 1772.24 psi
+  - ``operating_point`` (HB oil, thp=200, reservoir pr=3000): rate 1391.4 → 2019.0 stb/d, bhp 2206.3 → 1778.5 psi
+
+  RST and notebook examples updated to match the corrected values.
+
+- **nodal.fthp**: New reverse-solve function. ``fthp(bhp, completion, ...)`` returns the tubing head pressure that produces the specified BHP under the given VLP correlation. Wraps ``bisect_solve`` over ``fbhp``, accepts the same flow/well parameters as ``fbhp``, and has matching units/metric handling. Users no longer need to hand-roll a bisection for wellhead back-calculation workflows.
+
+- **nodal.fbhp ``return_profile=True``**: New kwarg. When enabled, ``fbhp`` returns a ``NodalResult`` with per-segment-boundary ``md``, ``tvd``, and ``p`` arrays (plus scalar ``bhp``) instead of just the bottom-hole scalar. Exposes the wellbore pressure traverse without forking the internal segment march. Metric-aware outputs.
+
+- **nodal.operating_point extensions**:
+
+  - New ``injection=False`` kwarg, forwarded to internal ``fbhp`` and ``outflow_curve`` calls so injection wells can be solved directly through ``operating_point``. Previously ``injection=True`` was honoured only by direct ``fbhp`` calls.
+  - New ``converged`` key in the returned ``NodalResult``. ``True`` when the VLP/IPR bisection succeeded, ``False`` when it fell back to ``rate=0, bhp=pr`` (no intersection). Surfaces a condition that previously looked like a plausible zero-rate answer.
+
+- **nodal.outflow_curve dict key**: Returned ``NodalResult`` now carries both ``'rate'`` and ``'rates'`` entries (same list). ``'rate'`` matches ``ipr_curve`` and ``operating_point``; ``'rates'`` is kept for backward compatibility.
+
+- **SoreideWhitson framework / salinity_method exposed**: New ``framework`` (``'proposed'`` | ``'sw_original'`` | ``'dropin'``) and ``salinity_method`` (``'gamma_phi'`` | ``'embedded'`` | ``'explicit'`` | ``'sechenov'`` | ``'auto'``) constructor kwargs, forwarded to the VLE engine. Defaults unchanged (``'proposed'`` + ``'gamma_phi'``). Combining ``framework='proposed'`` with ``salinity_method='embedded'`` now emits a warning because the engine falls back to ``gamma_phi`` for the ``proposed`` kij set.
+
+- **Brine ``ppm`` / ``wt`` conflict detection**: ``brine_props``, ``CO2_Brine_Mixture``, and ``SoreideWhitson`` now raise ``ValueError("Supply either ... not both.")`` when both aliases are passed. Previously one silently won with no feedback.
+
+- **Oil API cleanup**:
+
+  - Removed private-helper re-exports ``_cofb_mccain``, ``_perrine_co_sat``, ``_resolve_pb_rsb``, ``_build_bot_tables``, ``_format_bot_results`` from ``pyrestoolbox.oil`` public namespace. Still reachable via ``pyrestoolbox.oil._tables`` / ``._density`` / ``._compressibility`` for advanced users; ``simtools.make_bot_og`` updated internally.
+  - Dead imports removed across ``_compressibility``, ``_correlations``, ``_density``, ``_harmonize``, ``_tables`` sub-files (11 symbols total).
+  - Valko-McCain (2003) coefficient matrices for ``sg_st_gas`` and ``oil_rs_st`` extracted to ``_constants.py`` with paper citations, per CLAUDE.md named-constants rule.
+
+- **Oil documentation sync**: ``docs/oil.rst`` updated — ``oil_deno`` parameter listed as ``sg_o`` (matches code; was incorrectly ``sg_sto``). ``make_bot_og`` result-dict table now documents ``vis_frac`` (was previously omitted despite being returned).
+
+- **DCA internals**: 20 previously inline magic numbers extracted to named constants at the top of ``dca.py`` (Arps b-grid 0.05/0.96/0.01, Duong trap bounds and curve_fit bounds, logistic fit bounds, hyperbolic numerical floor). ``_build_decline_result`` helper deduplicates R-squared/residual/DeclineResult construction across the six ``_fit_*`` helpers (~60 lines removed).
+
+- 726 validation tests (up from 716 in 3.3.0). New coverage for ``fthp`` roundtrip, ``fbhp`` pressure-traverse return, ``operating_point.converged``, ``SoreideWhitson`` framework/salinity_method validation, and the three ``ppm``/``wt`` conflict raises.
+
 Changelist in 3.3.0:
 
 - **BNS Z-factor / critical-property coupling**: When either ``zmethod`` or ``cmethod`` is ``BNS``, both are now forced to ``BNS`` for thermodynamic consistency with a ``UserWarning`` naming the overruled counterpart. ``h2 > 0`` continues to auto-select BNS silently. Non-BNS methods (e.g. ``DAK`` + ``SUT``) remain freely mixable. Implemented via a single ``_resolve_methods`` helper applied at all gas public entry points plus ``GasPVT.__init__``.