pyrestoolbox 3.2.0__tar.gz → 3.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyrestoolbox
-Version: 3.2.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.2.0 → pyrestoolbox-3.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "pyrestoolbox"
-version = "3.2.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.2.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:
@@ -315,7 +319,7 @@ def brine_props(p: float = None, degf: float = None, wt: float = None, ch4_sat:
         / ((Mpa - vap_pressure) - 2 * dlambdadptm * m)
     )  # Eq 4.33
 
-    zee = gas.gas_z(p=p, sg=_SG_METHANE, degf=degf, zmethod='BNS',
+    zee = gas.gas_z(p=p, sg=_SG_METHANE, degf=degf, zmethod='BNS', cmethod='BNS',
                     co2=0, h2s=0, n2=0, h2=0)  # Z-Factor of pure methane
 
     vmch4g = zee * _R_CM3_MPA * degk / Mpa  # Eq 4.34
@@ -342,7 +346,7 @@ def brine_props(p: float = None, degf: float = None, wt: float = None, ch4_sat:
 
 
 
-    zee_sc = gas.gas_z(p=psc, sg=_SG_METHANE, degf=tsc, zmethod='BNS',
+    zee_sc = gas.gas_z(p=psc, sg=_SG_METHANE, degf=tsc, zmethod='BNS', cmethod='BNS',
                        co2=0, h2s=0, n2=0, h2=0)
     vmch4g_sc = zee_sc * _R_CM3_MPA * (273 + 15) / 0.1013  # Eq 4.34
     rsw_new = mch4 * vmch4g_sc / ((1000 + m * 58.4428) * vb0_sc)
@@ -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
@@ -1552,7 +1588,7 @@ class SoreideWhitson:
                 self.gas_comp.get(g, 0) * _SW_GAS_MW.get(g, 28.97)
                 for g in self.gas_comp
             ) / MW_AIR
-            zee = gas.gas_z(p=self.psia, sg=gas_sg, degf=self.degF, zmethod='BNS',
+            zee = gas.gas_z(p=self.psia, sg=gas_sg, degf=self.degF, zmethod='BNS', cmethod='BNS',
                             co2=self.gas_comp.get('CO2', 0),
                             h2s=self.gas_comp.get('H2S', 0),
                             n2=self.gas_comp.get('N2', 0),
@@ -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.2.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.2.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