pyrestoolbox 3.1.5__tar.gz → 3.2.0__tar.gz

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

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

{pyrestoolbox-3.1.5 → pyrestoolbox-3.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "pyrestoolbox"
-version = "3.1.5"
+version = "3.2.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.1.5 → pyrestoolbox-3.2.0}/pyrestoolbox/brine/_lib_vle_engine.py

@@ -2100,9 +2100,12 @@ class SWMultiComponentFlash:
         z = np.asarray(z, dtype=float)
         z = z / np.sum(z)
 
-        # Rust acceleration path — gamma is always passed explicitly
-        # to prevent Rust from using its built-in ks model (which lacks
-        # the specialised Dubessy/Akinfiev models for CO2/H2S).
+        # Rust acceleration path — gamma is always passed explicitly.
+        # The Rust entry point trusts the caller-supplied gamma and never
+        # substitutes its own S&W Eq 8 ks fallback. framework='proposed'
+        # 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:
             try:
                 gamma_arr = np.asarray(gamma, dtype=float) if gamma is not None \

{pyrestoolbox-3.1.5 → pyrestoolbox-3.2.0}/pyrestoolbox/brine/brine.py

@@ -456,6 +456,7 @@ class CO2_Brine_Mixture():
                 .Rs      : CO2 Saturated Brine solution gas ratio (sm3/sm3 or scf/stb), relative to standard conditions
                 .Cf_usat : Brine undersaturated compressibility (1/Bar or 1/psi). The compressibility with constant Rs
                 .Cf_sat  : Brine saturated compressibility (1/Bar or 1/psi). The compressibility with reducing Rs under depletion
+                .converged: True if the Spycher-Pruess fugacity iteration reached tolerance, False otherwise
                             
             Usage example for 5000 psia x 275 deg F and 3% NaCl brine:
                 mix = brine.CO2_Brine_Mixture(pres = 5000, temp = 275, ppm = 30000, metric = False)
@@ -523,6 +524,7 @@ class CO2_Brine_Mixture():
         self.Cf_sat = None                # Saturated brine compressibility (1/Bar or 1/psi). Compressibility with changing Rs
         self.CO2_sat = False              # Flag to determine if in P-T range for saturated liquid CO2 K values
         self.repeat = False               # Flag to trigger repeat of calculations depending on whether CO2 is saturated liquid phase
+        self.converged = True             # Spycher-Pruess fugacity iteration convergence flag
         #self.EzrokhiDenA = None           # Ezrokhi coefficient array for density (to be calculated with ezrokhi() function)
         #self.EzrokhiVisB = None           # Ezrokhi coefficient array for viscosity (to be calculated with ezrokhi() function)
         self.Rs_STD = None                # Dissolved CO2 remaining at standard conditions (sm3/sm3)
@@ -1125,6 +1127,7 @@ class CO2_Brine_Mixture():
                 iternum += 1
 
             if err > EPS:
+                self.converged = False
                 import warnings
                 warnings.warn(
                     f"Spycher CO2-brine iteration did not converge in {iternum} iterations "

{pyrestoolbox-3.1.5 → pyrestoolbox-3.2.0}/pyrestoolbox/dca/dca.py

@@ -323,10 +323,13 @@ def duong_cum(qi, a, m, t):
     if np.any(t <= 0):
         raise ValueError("Time must be positive for Duong model")
 
-    # Generate fine time grid for integration
+    # Generate fine time grid for integration. Lower bound must be strictly
+    # less than ti to give np.linspace an ascending range, otherwise trapezoid
+    # integrates over a descending axis and returns negative cumulative.
     results = np.zeros_like(t, dtype=float)
     for i, ti in enumerate(t):
-        t_fine = np.linspace(0.001, ti, max(500, int(ti * 10)))
+        lower = min(0.001, ti * 0.001)
+        t_fine = np.linspace(lower, ti, max(500, int(ti * 10)))
         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)
 
@@ -958,6 +961,12 @@ def forecast(result, t_end, dt=1.0, q_min=0.0, uptime=1.0, ratios=None):
     -------
     ForecastResult
     """
+    if dt <= 0:
+        raise ValueError(f"dt must be positive, got {dt}")
+    if t_end <= 0:
+        raise ValueError(f"t_end must be positive, got {t_end}")
+    if not (0.0 < uptime <= 1.0):
+        raise ValueError(f"uptime must be in (0, 1], got {uptime}")
     t = np.arange(dt, t_end + dt / 2, dt)
 
     if result.method == 'duong':

{pyrestoolbox-3.1.5 → pyrestoolbox-3.2.0}/pyrestoolbox/docs/changelist.rst

@@ -1,3 +1,24 @@
+Changelist in 3.2.0:
+
+- **DCA bug fixes**:
+
+  - ``dca.duong_cum`` — fixed linspace-inversion bug where cumulative volume integrated over a descending axis for ``t < 0.001`` (small-t inputs) and returned a negative value. Lower bound of the integration is now ``min(0.001, t * 0.001)`` so the grid is always ascending.
+  - ``dca.forecast`` — now validates ``dt > 0``, ``t_end > 0`` and ``uptime`` in ``(0, 1]`` at entry with clear ``ValueError`` messages. Previously ``dt = 0`` raised an opaque ``ZeroDivisionError`` and out-of-range ``uptime`` was silently accepted.
+
+- **Rachford-Rice solver consolidation**: ``simtools.rr_solver`` is now a thin wrapper that delegates to the canonical ``pyrestoolbox.brine._lib_vle_engine.rr_solver`` (Nielsen & Lia 2022). Removes ~100 lines of duplicated iterative code plus the dead ``ensure_numpy_array`` helper. Inputs validated for length/sum before delegation; behaviour is preserved (``EPS_T=1e-15``, ``max_iter=100``).
+
+- **Rust Sechenov fallback guard**: ``src/vle/mod.rs::flash_tp_rust`` no longer silently substitutes its S&W Eq 8 ``ks`` fallback when a caller passes all-ones ``gamma`` with ``salinity > 0``. The caller-supplied ``gamma`` is now always trusted, eliminating any risk that Python ``framework='proposed'`` calls bypass the specialised Dubessy/Akinfiev/Li/Mao-Duan/Duan-Sun ``ks`` models. ``calc_equilibrium_rust`` retains the S&W Eq 8 path but now carries a prominent doc warning. Python path unchanged (Python always passes the correct ``gamma``).
+
+- **Convergence flag on ``CO2_Brine_Mixture``**: New ``.converged`` attribute on the class. ``True`` after a successful Spycher-Pruess fugacity iteration, ``False`` when the 100-iteration limit is hit (matching the existing ``RuntimeWarning``). Lets downstream callers detect non-convergence programmatically.
+
+- **``sensitivity.tornado`` robustness**: Raises ``ValueError`` if ``base_result`` is not finite (NaN/Inf), and if any ``ranges[param]`` has ``lo > hi``. Previously returned ``nan`` or ``inf`` sensitivities that silently corrupted tornado plots.
+
+- **``layer`` module dedup**: Five copies of the EXP/LANG dispatch (B-clamp, flow-fraction evaluation) consolidated into three private helpers (``_clamp_b``, ``_b_max``, ``_flow_fraction_at_x``). No behaviour change.
+
+- **``recommend`` module docstrings**: ``sg`` on ``recommend_gas_methods`` and ``well_type`` on ``recommend_vlp_method`` are currently unused by the decision logic. Docstrings now flag them as reserved for future rules. Signatures preserved for backward compatibility.
+
+- 701 validation tests (up from 696 in 3.1.5).
+
 Changelist in 3.1.5:
 
 - **Agent-friendly UX**:

{pyrestoolbox-3.1.5 → pyrestoolbox-3.2.0}/pyrestoolbox/layer/layer.py

@@ -41,6 +41,35 @@ import numpy.typing as npt
 
 from pyrestoolbox.shared_fns import bisect_solve
 
+
+_B_MIN = 1e-6
+_B_MAX_EXP = 709
+_B_MAX_LANG = 25000
+
+
+def _b_max(method: str) -> float:
+    """Upper bookend for B in bisection for the given Lorenz method."""
+    return _B_MAX_LANG if method == "LANG" else _B_MAX_EXP
+
+
+def _clamp_b(B: float, method: str) -> float:
+    """Clamp B to [_B_MIN, _b_max(method)]."""
+    return min(max(B, _B_MIN), _b_max(method))
+
+
+def _flow_fraction_at_x(B: float, x: float, method: str) -> float:
+    """Flow fraction from best phi_h fraction x, given B and method.
+
+    EXP:  (1 - exp(-B*x)) / (1 - exp(-B))
+    LANG: (VL * x) / (PL + x) with PL = 1/B, VL = PL + 1
+    """
+    if method == "LANG":
+        PL = 1 / B
+        VL = PL + 1
+        return (VL * x) / (PL + x)
+    return (1 - np.exp(-B * x)) / (1 - np.exp(-B))
+
+
 def lorenz2b(lorenz: float, lrnz_method: str = "EXP") -> float:
     """ Returns B-factor that characterizes the Lorenz function
         Lorenz: Lorenz coefficient (0-1)
@@ -63,37 +92,22 @@ def lorenz2b(lorenz: float, lrnz_method: str = "EXP") -> float:
         return 0.0  # Homogeneous — no heterogeneity
 
     if lorenz < 0.000333:
-        B = 2 / 1000
-        if method == "LANG":
-            B = 1 / 1000
-        return B
+        return 1 / 1000 if method == "LANG" else 2 / 1000
     if lorenz > 0.997179125528914:
-        B = 709
-        if method == "LANG":
-            B = 25000
-        return B
+        return _b_max(method)
 
-    # Set bookends for B
-    hi = 709
-    if method == "LANG":
-        hi = 25000
-    lo = 0.000001
+    hi = _b_max(method)
+    lo = _B_MIN
     args = (lorenz, method)
 
     def LorenzErr(args, B):
         lorenz, method = args
-        B = max(B, 0.000001)
-        if method == "EXP":
-            B = min(B, 709)
-            err = 2 * ((1 / (np.exp(B) - 1)) - (1 / B)) + 1 - lorenz
-        else:
-            B = min(B, 25000)
+        B = _clamp_b(B, method)
+        if method == "LANG":
             PL = 1 / B
             VL = PL + 1
-            err = (
-                VL - PL * VL * np.log(VL) + PL * VL * np.log(PL) - 0.5
-            ) * 2 - lorenz
-        return err
+            return (VL - PL * VL * np.log(VL) + PL * VL * np.log(PL) - 0.5) * 2 - lorenz
+        return 2 * ((1 / (np.exp(B) - 1)) - (1 / B)) + 1 - lorenz
 
     rtol = 0.0000001
     return bisect_solve(args, LorenzErr, lo, hi, rtol)
@@ -113,16 +127,12 @@ def lorenzfromb(B: float, lrnz_method: str = "EXP") -> float:
     method = lrnz_method.upper()
     if B <= 0:
         return 0.0  # B=0 means homogeneous (Lc=0)
-    B = max(B, 0.000001)
+    B = _clamp_b(B, method)
     if method == "LANG":
-        B = min(B, 25000)
         PL = 1 / B
         VL = PL + 1
-        L = (VL - PL * VL * np.log(VL) + PL * VL * np.log(PL) - 0.5) * 2
-    else:
-        B = min(B, 709)
-        L = 2 * (1 / (np.exp(B) - 1) - (1 / B)) + 1
-    return L
+        return (VL - PL * VL * np.log(VL) + PL * VL * np.log(PL) - 0.5) * 2
+    return 2 * (1 / (np.exp(B) - 1) - (1 / B)) + 1
 
 
 def lorenz_from_flow_fraction(
@@ -155,23 +165,15 @@ def lorenz_from_flow_fraction(
         return lorenzfromb(B, method)
 
     # Set bookends and first guess of B
-    hi = 709
-    lo = 0.000001
+    hi = _B_MAX_EXP
+    lo = _B_MIN
     args = (kh_frac, phih_frac, method)
 
     def BErr(args, B):
         kh_frac, phih_frac, method = args
         method = method.upper()
-        B = max(B, 0.000001)
-        if method == "EXP":
-            B = min(B, 709)
-            err = (1 - np.exp(-B * phih_frac)) / (1 - np.exp(-B)) - kh_frac
-        else:
-            B = min(B, 25000)
-            PL = 1 / B
-            VL = PL + 1
-            err = (VL * phih_frac) / (PL + phih_frac) - kh_frac
-        return err
+        B = _clamp_b(B, method)
+        return _flow_fraction_at_x(B, phih_frac, method) - kh_frac
 
     rtol = 0.0000001
     B = bisect_solve(args, BErr, lo, hi, rtol)
@@ -203,16 +205,8 @@ def lorenz_2_flow_frac(
     if B < 0:  # Need to calculate B
         B = lorenz2b(lorenz=lorenz, lrnz_method=lrnz_method)
 
-    B = max(B, 0.000001)
-    if method == "EXP":
-        B = min(B, 709)
-        fraction = (1 - np.exp(-B * phih_frac)) / (1 - np.exp(-B))
-    else:
-        B = min(B, 25000)
-        PL = 1 / B
-        VL = PL + 1
-        fraction = (VL * phih_frac) / (PL + phih_frac)
-    return fraction
+    B = _clamp_b(B, method)
+    return _flow_fraction_at_x(B, phih_frac, method)
 
 
 def lorenz_2_layers(
@@ -255,11 +249,7 @@ def lorenz_2_layers(
     if B < 0:  # Need to calculate B
         B = lorenz2b(lorenz=lorenz, lrnz_method=lrnz_method)
 
-    B = max(B, 0.000001)
-    if method == "EXP":
-        B = min(B, 709)
-    else:
-        B = min(B, 25000)
+    B = _clamp_b(B, method)
 
     user_layers = False
     if len(phi_h_fracs) > 1:
@@ -280,12 +270,7 @@ def lorenz_2_layers(
     sumkh = []
 
     for layer in phih:
-        if method == "EXP":
-            sumkh.append((1 - np.exp(-B * layer)) / (1 - np.exp(-B)))
-        else:
-            PL = 1 / B
-            VL = PL + 1
-            sumkh.append((VL * layer) / (PL + layer))
+        sumkh.append(_flow_fraction_at_x(B, layer, method))
 
     kh = (
         np.array([sumkh[i] - sumkh[i - 1] for i in range(1, len(sumkh))])

{pyrestoolbox-3.1.5 → pyrestoolbox-3.2.0}/pyrestoolbox/recommend/recommend.py

@@ -75,7 +75,9 @@ def recommend_gas_methods(sg: float = 0.65, co2: float = 0, h2s: float = 0,
     Parameters
     ----------
     sg : float
-        Gas specific gravity (default 0.65).
+        Gas specific gravity (default 0.65). Currently unused by the decision
+        logic — accepted for API consistency and reserved for future rules
+        (e.g. heavy gas / condensate-laden streams). Breaking removal deferred.
     co2 : float
         CO2 mole fraction (default 0).
     h2s : float
@@ -90,6 +92,7 @@ def recommend_gas_methods(sg: float = 0.65, co2: float = 0, h2s: float = 0,
     dict of str to MethodRecommendation
         Keys: 'zmethod', 'cmethod'.
     """
+    _ = sg  # reserved, see docstring
     inerts = co2 + h2s + n2 + h2
     recs = {}
 
@@ -204,13 +207,16 @@ def recommend_vlp_method(deviation: float = 0,
     deviation : float
         Maximum wellbore deviation from vertical in degrees (default 0).
     well_type : str
-        'gas' or 'oil' (default 'gas').
+        'gas' or 'oil' (default 'gas'). Currently unused by the decision logic
+        — accepted for API consistency and reserved for future fluid-specific
+        recommendations. Breaking removal deferred.
 
     Returns
     -------
     dict of str to MethodRecommendation
         Key: 'vlp_method'.
     """
+    _ = well_type  # reserved, see docstring
     recs = {}
 
     if deviation <= 30:

{pyrestoolbox-3.1.5 → pyrestoolbox-3.2.0}/pyrestoolbox/sensitivity/sensitivity.py

@@ -39,6 +39,7 @@ __all__ = [
     'SweepResult', 'TornadoEntry', 'TornadoResult',
 ]
 
+import math
 from dataclasses import dataclass, field
 from typing import Callable, Dict, Any, List, Optional
 
@@ -172,11 +173,21 @@ def tornado(func: Callable, base_kwargs: Dict[str, Any],
     base_raw = func(**base_kwargs)
     base_val = _extract_result(base_raw, result_key)
     base_result = float(base_val)
+    if not math.isfinite(base_result):
+        raise ValueError(
+            f"base_result is not finite ({base_result}); "
+            f"tornado sensitivities would be undefined. "
+            f"Check base_kwargs and result_key."
+        )
 
     entries = []
     for param, (lo, hi) in ranges.items():
         if param not in base_kwargs:
             raise ValueError(f"Parameter '{param}' not found in base_kwargs")
+        if lo > hi:
+            raise ValueError(
+                f"ranges['{param}'] = ({lo}, {hi}): low must be <= high"
+            )
 
         kwargs_lo = dict(base_kwargs)
         kwargs_lo[param] = lo

{pyrestoolbox-3.1.5 → pyrestoolbox-3.2.0}/pyrestoolbox/simtools/simtools.py

@@ -1025,19 +1025,11 @@ def zip_check_sim_deck(files2scrape = [], tozip = True, console_summary = True,
     else:
         return
 
-def ensure_numpy_array(data):
-    if isinstance(data, list):
-        return np.array(data)
-    elif isinstance(data, np.ndarray):
-        return data
-    else:
-        raise ValueError("Input is neither a list nor a numpy array.")
-                               
 def rr_solver(
     zi: Union[npt.ArrayLike, list], ki: Union[npt.ArrayLike, list]
 ) -> Tuple[int, np.ndarray, np.ndarray, float, float]:
     """
-    Solves for the root of the Rachford-Rice equation using a method that 
+    Solves for the root of the Rachford-Rice equation using a method that
     gracefully handles catastrophic roundoff errors.
     The method is outlined in 2022 'Fluid Phase Equilibria' paper by M. Nielsen & H. Lia
 
@@ -1052,8 +1044,10 @@ def rr_solver(
     V: Vapor molar fraction (float)
     L: Liquid molar fraction (float)
     """
-    zi = ensure_numpy_array(zi)
-    ki = ensure_numpy_array(ki)
+    from pyrestoolbox.brine._lib_vle_engine import rr_solver as _brine_rr_solver
+
+    zi = np.asarray(zi, dtype=float)
+    ki = np.asarray(ki, dtype=float)
 
     if len(zi) == 0 or len(ki) == 0:
         raise ValueError("zi and ki arrays must not be empty")
@@ -1063,76 +1057,8 @@ def rr_solver(
     zi_sum = np.sum(zi)
     if zi_sum <= 0:
         raise ValueError("Sum of zi must be positive")
-    zi = zi / zi_sum  # Normalize feed compositions
-    
-    def rr(V: float) -> float:
-        return np.dot(zi, (ki - 1) / (1 + V * (ki - 1)))
-    
-    def h(b: float) -> float:    # Eq 12b
-        return np.sum(zi*b/(1+b*(phi_min - ci)))
-    
-    def dh(b: float) -> float:   # Eq 16b
-        return np.sum(zi/(1 + b*(phi_min - ci)) ** 2)
-    
-    N_it = 0
-    
-    # Assess if solution nearest vapor or liquid solutions
-    # and appropriately assign pseudo phase and ki's
-    near_vapor = False
-    if rr(0.5) > 0:
-        near_vapor = True
-    
-    ki_hat = ki
-    if near_vapor:
-        ki_hat = 1/ki
-    
-    ci = np.where(np.abs(1 - ki_hat) > 1e-10, 1/(1-ki_hat), 0.0)  # Eq 10
-        
-    # Will use the transformed solution in terms of b (Eq 14b)
-    phi_max = min(1/(1-min(ki_hat)), 0.5)    # Eq 11a
-    phi_min = 1/(1-max(ki_hat))              # Eq 11b with upper 0.5 limit given we have chosen this phase
-    b_min = 1/(phi_max - phi_min)            # Eq 15
-    b_max = np.inf
-    
-    b = 1/(0.25 - phi_min)
-    N_it = 0
-    h_b = np.inf
-
-    while abs(h_b) > EPS_T:
-        N_it += 1
 
-        h_b = h(b)
-        dh_b = dh(b)
-
-        if h_b > 0:
-            b_max = b
-        else:
-            b_min = b
-
-        b = b - h_b / dh_b
-
-        if b < b_min or b > b_max:
-            b = (b_min + b_max) / 2
-
-        if N_it > MAX_ITR:
-            break
-    
-    ui = -zi*ci*b/(1+b*(phi_min-ci))    # Eq 27b 
-    phi = (1+b*phi_min)/b               # Rearranged Eq 14b
-    
-    if near_vapor:
-        L = phi
-        V = 1 - L
-        yi = ui
-        xi = ki_hat * ui                # Eq 28
-        
-    else:
-        V = phi
-        L = 1 - V
-        xi = ui
-        yi = ki_hat * ui                # Eq 28
-        
-    return N_it, yi, xi, V, L
+    return _brine_rr_solver(zi, ki, tol=EPS_T, max_iter=MAX_ITR)
 
 
 # =============================================================================

{pyrestoolbox-3.1.5 → pyrestoolbox-3.2.0}/src/vle/mod.rs

@@ -57,10 +57,14 @@ fn resolve_comp_names(comp_names: &[String]) -> PyResult<Vec<usize>> {
 /// * `p_pa` - Pressure in Pascal
 /// * `z` - Feed composition (will be normalized)
 /// * `comp_names` - Component names (e.g., ["H2O", "CH4", "CO2"])
-/// * `salinity` - NaCl molality (mol/kg water)
+/// * `salinity` - NaCl molality (mol/kg water). Informational only; the caller
+///                is responsible for baking salinity into `gamma`.
 /// * `mode` - "AQ" for aqueous phase BIPs, "NA" for non-aqueous
-/// * `gamma` - Activity coefficient array (same length as z).
-///             Use all-ones for freshwater or when salinity is handled externally.
+/// * `gamma` - Activity coefficient array (same length as z). Must be computed
+///             by the caller. For framework='proposed', specialized ks models
+///             (Dubessy/Akinfiev/Li/Mao-Duan/Duan-Sun) live on the Python side
+///             — this Rust entry point must not substitute its own S&W Eq 8
+///             fallback silently. Use `1.0` for gases in freshwater.
 ///
 /// # Returns
 /// Tuple (V, x_vec, y_vec) where V is vapor fraction, x is liquid comp, y is vapor comp.
@@ -74,6 +78,10 @@ pub fn flash_tp_rust(
     mode: String,
     gamma: Vec<f64>,
 ) -> PyResult<(f64, Vec<f64>, Vec<f64>)> {
+    // Salinity arg is retained for signature stability / future diagnostics;
+    // currently unused because gamma is always caller-supplied.
+    let _ = salinity;
+
     // Validate inputs
     if !t_k.is_finite() || t_k <= 0.0 {
         return Err(PyValueError::new_err("Temperature must be positive and finite"));
@@ -104,23 +112,13 @@ pub fn flash_tp_rust(
 
     let comp_indices = resolve_comp_names(&comp_names)?;
 
-    // If salinity > 0 and mode is AQ and gamma is all-ones, compute gamma internally
-    let gamma_eff = if salinity > 0.0
-        && mode_aq
-        && gamma.iter().all(|&g| (g - 1.0).abs() < 1e-15)
-    {
-        flash::calc_gamma(&comp_indices, t_k, salinity)
-    } else {
-        gamma
-    };
-
     let (v, x, y, _converged) = flash::flash_tp(
         t_k,
         p_pa,
         &z,
         &comp_indices,
         mode_aq,
-        &gamma_eff,
+        &gamma,
         200,
         1e-10,
     );
@@ -134,6 +132,17 @@ pub fn flash_tp_rust(
 /// Flash 2 (kij_NA) -> non-aqueous phase y
 /// True K-values: K_i = y_i(Flash 2) / x_i(Flash 1)
 ///
+/// # Warning
+/// This entry point computes Sechenov activity coefficients internally using
+/// **S&W Equation 8 only**. It does NOT route CO2/H2S through the specialized
+/// Dubessy/Akinfiev/Li/Mao-Duan/Duan-Sun models used by the Python
+/// framework='proposed' path. Callers who need the specialized ks models must
+/// compute gamma Python-side and call `flash_tp_rust` twice (AQ then NA) with
+/// the pre-computed gamma, rather than using this convenience entry point.
+/// Not currently called from Python `SWFlashEngine` — Python computes gamma
+/// via `self.calc_gamma(...)` with the correct framework dispatch and calls
+/// `flash_tp_rust` directly.
+///
 /// # Arguments
 /// * `t_k` - Temperature in Kelvin
 /// * `p_pa` - Pressure in Pascal