pyrestoolbox 3.8.2__tar.gz → 3.8.4__tar.gz

{pyrestoolbox-3.8.2 → pyrestoolbox-3.8.4}/.github/workflows/tests.yml

@@ -63,6 +63,32 @@ jobs:
       - name: Run full test suite (Rust + parity)
         run: python3 -m pytest pyrestoolbox/tests/ -q
 
+  # ── MCP server (separate distribution in mcp/) on both SDK majors ────
+  # The server picks FastMCP (1.x) or MCPServer (2.x) at import; test both so
+  # an SDK release that breaks either path fails here, not in a deployment.
+  test-mcp:
+    name: MCP server (${{ matrix.mcp }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        mcp: ["mcp>=1.2,<2", "mcp>=2,<3"]
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install numpy scipy pandas tabulate openpyxl mpmath ilt-inversion pytest "${{ matrix.mcp }}"
+
+      # Library from the source tree (pure Python), server from mcp/.
+      - name: Run MCP tests
+        env:
+          PYRESTOOLBOX_NO_RUST: "1"
+        run: PYTHONPATH="$PWD:$PWD/mcp" python3 -m pytest mcp/tests/ -q
+
   # ── Complexity ratchet (new code only; existing offenders baselined) ─
   complexity:
     name: Complexity ratchet

{pyrestoolbox-3.8.2 → pyrestoolbox-3.8.4}/Cargo.lock

@@ -152,7 +152,7 @@ dependencies = [
 
 [[package]]
 name = "pyrestoolbox-native"
-version = "3.8.2"
+version = "3.8.4"
 dependencies = [
  "pyo3",
  "rug",

{pyrestoolbox-3.8.2 → pyrestoolbox-3.8.4}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "pyrestoolbox-native"
-version = "3.8.2"
+version = "3.8.4"
 edition = "2021"
 license = "GPL-3.0-or-later"
 description = "Rust acceleration extensions for pyResToolbox"

{pyrestoolbox-3.8.2 → pyrestoolbox-3.8.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyrestoolbox
-Version: 3.8.2
+Version: 3.8.4
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Rust
 Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
@@ -45,7 +45,7 @@ Includes functions to perform calculations including;
 - Nodal analysis operating point determination
 - Eclipse VFP table generation (VFPPROD and VFPINJ keywords)
 - PVT Calculations for oil
-- PVT calculation for gas, including up to 100% inerts for CO2, H2S, N2 and H2
+- PVT calculation for gas, including up to 100% inerts for CO2, H2S, N2, H2 and He
 - Gas caloric properties (enthalpy, Cp, Cv, Joule-Thomson coefficient) from the BNS tuned Peng Robinson EOS
 - Gas hydrate formation prediction with thermodynamic inhibitor calculations
 - Return critical parameters for typical components

{pyrestoolbox-3.8.2 → pyrestoolbox-3.8.4}/README.rst

@@ -20,7 +20,7 @@ Includes functions to perform calculations including;
 - Nodal analysis operating point determination
 - Eclipse VFP table generation (VFPPROD and VFPINJ keywords)
 - PVT Calculations for oil
-- PVT calculation for gas, including up to 100% inerts for CO2, H2S, N2 and H2
+- PVT calculation for gas, including up to 100% inerts for CO2, H2S, N2, H2 and He
 - Gas caloric properties (enthalpy, Cp, Cv, Joule-Thomson coefficient) from the BNS tuned Peng Robinson EOS
 - Gas hydrate formation prediction with thermodynamic inhibitor calculations
 - Return critical parameters for typical components

{pyrestoolbox-3.8.2 → pyrestoolbox-3.8.4}/mcp/Dockerfile

@@ -7,7 +7,7 @@ FROM python:3.11-slim
 
 # Pin the library version for reproducible corporate deployments; bump
 # deliberately and rebuild.
-ARG PYRESTOOLBOX_VERSION=3.7.0
+ARG PYRESTOOLBOX_VERSION=3.8.2
 
 WORKDIR /app
 COPY . /app/mcp

{pyrestoolbox-3.8.2 → pyrestoolbox-3.8.4}/mcp/pyproject.toml

@@ -11,8 +11,8 @@ authors = [{name = "Mark W. Burgoyne", email = "mark.w.burgoyne@gmail.com"}]
 keywords = ["mcp", "petroleum", "reservoir", "pyrestoolbox"]
 requires-python = ">=3.10"
 dependencies = [
-    "mcp>=1.2,<2",
-    "pyrestoolbox>=3.7",
+    "mcp>=1.2,<3",
+    "pyrestoolbox>=3.8.2",
 ]
 readme = "README.md"
 

{pyrestoolbox-3.8.2 → pyrestoolbox-3.8.4}/mcp/pyrestoolbox_mcp/server.py

@@ -17,7 +17,12 @@ as MCP resources (docs://gas, docs://oil, ...).
 import importlib
 import inspect
 
-from mcp.server.fastmcp import FastMCP
+try:  # mcp >= 2 renamed FastMCP to MCPServer
+    from mcp.server.mcpserver import MCPServer as _MCPServer
+    _MCP_V2 = True
+except ImportError:  # mcp 1.x
+    from mcp.server.fastmcp import FastMCP as _MCPServer
+    _MCP_V2 = False
 
 from pyrestoolbox_mcp.serialize import to_jsonable
 
@@ -37,7 +42,7 @@ ALLOWED_MODULES = {
     "sensitivity": "Parameter sweeps and tornado analysis",
 }
 
-mcp = FastMCP(
+mcp = _MCPServer(
     "pyrestoolbox",
     instructions=(
         "Petroleum/reservoir engineering calculations from the pyrestoolbox "
@@ -250,7 +255,7 @@ def _construct(dotted, key, spec):
 @mcp.tool()
 def recommend_methods(sg: float = 0.65, co2: float = 0, h2s: float = 0,
                       n2: float = 0, h2: float = 0, api: float | None = None,
-                      deviation: float = 0, well_type: str = "gas") -> dict:
+                      deviation: float = 0, well_type: str = "gas", he: float = 0) -> dict:
     """Recommend correlation methods for a fluid/well, with rationale.
 
     Composition fractions are molar. api: stock tank oil gravity (include to
@@ -263,7 +268,7 @@ def recommend_methods(sg: float = 0.65, co2: float = 0, h2s: float = 0,
     from pyrestoolbox import recommend
     recs = recommend.recommend_methods(sg=sg, co2=co2, h2s=h2s, n2=n2, h2=h2,
                                        api=api, deviation=deviation,
-                                       well_type=well_type)
+                                       well_type=well_type, he=he)
     return to_jsonable(recs)
 
 
@@ -291,12 +296,12 @@ def co2_brine_props(pres: float, temp: float, ppm: float = 0,
 def sw_brine_props(pres: float, temp: float, ppm: float = 0,
                    y_CO2: float = 0, y_H2S: float = 0, y_N2: float = 0,
                    y_H2: float = 0, sg: float = 0.65, cw_sat: bool = False,
-                   metric: bool = False) -> dict:
+                   metric: bool = False, y_He: float = 0) -> dict:
     """Multicomponent gas-saturated brine properties (Soreide-Whitson VLE).
 
     pres: pressure (psia, or barsa if metric=True). temp: temperature
     (deg F, or deg C if metric=True). ppm: NaCl-equivalent salinity.
-    y_*: molar fractions of CO2/H2S/N2/H2 in the equilibrium gas; the
+    y_*: molar fractions of CO2/H2S/N2/H2/He in the equilibrium gas; the
     remainder is hydrocarbon gas of specific gravity sg. Returns aqueous
     composition, brine density/viscosity triplets, Rs, water content and
     compressibilities.
@@ -304,7 +309,7 @@ def sw_brine_props(pres: float, temp: float, ppm: float = 0,
     from pyrestoolbox import brine
     sw = brine.SoreideWhitson(pres=pres, temp=temp, ppm=ppm, y_CO2=y_CO2,
                               y_H2S=y_H2S, y_N2=y_N2, y_H2=y_H2, sg=sg,
-                              cw_sat=cw_sat, metric=metric)
+                              cw_sat=cw_sat, metric=metric, y_He=y_He)
     keys = ("x", "bDen", "bVis", "bw", "Rs", "Rs_total", "water_content",
             "Cf_usat", "Cf_sat")
     return {k: to_jsonable(getattr(sw, k, None)) for k in keys}
@@ -382,13 +387,18 @@ def build_parser():
 
 def main():
     args = build_parser().parse_args()
-    if args.transport == "streamable-http":
-        mcp.settings.host = args.host
-        mcp.settings.port = args.port
-        # Independent request handling; no server-side session affinity needed
-        # behind a load balancer.
-        mcp.settings.stateless_http = True
-    mcp.run(transport=args.transport)
+    if args.transport != "streamable-http":
+        mcp.run(transport=args.transport)
+        return
+    # stateless_http: independent request handling; no server-side session
+    # affinity needed behind a load balancer.
+    http = {"host": args.host, "port": args.port, "stateless_http": True}
+    if _MCP_V2:
+        mcp.run(transport=args.transport, **http)
+    else:  # 1.x reads these from settings, not run()
+        for key, value in http.items():
+            setattr(mcp.settings, key, value)
+        mcp.run(transport=args.transport)
 
 
 if __name__ == "__main__":

{pyrestoolbox-3.8.2 → pyrestoolbox-3.8.4}/mcp/tests/test_server.py

@@ -4,9 +4,9 @@ Run from the repo root:
     PYTHONPATH=/home/mark/projects/pyResToolbox:/home/mark/projects/pyResToolbox/mcp \
         python3 -m pytest mcp/tests/ -q
 
-Most tests exercise the tool functions directly (FastMCP's @tool decorator
+Most tests exercise the tool functions directly (the SDK's @tool decorator
 returns the undecorated function). test_client_session_* run the full MCP
-protocol over an in-process transport.
+protocol over an in-process transport. The suite runs on mcp 1.x and 2.x.
 """
 
 import os
@@ -186,15 +186,19 @@ def test_fit_and_forecast_exponential():
 
 # ------------------------------------------------- full MCP protocol session
 
+def _in_memory_client():
+    """In-process client session: mcp 2.x Client takes the server directly;
+    1.x needs the memory-stream helper and the low-level server."""
+    if srv._MCP_V2:
+        from mcp.client import Client
+        return Client(srv.mcp)
+    from mcp.shared.memory import create_connected_server_and_client_session
+    return create_connected_server_and_client_session(srv.mcp._mcp_server)
+
+
 @pytest.mark.anyio
 async def test_client_session_tools_and_resources():
-    try:
-        from mcp.shared.memory import create_connected_server_and_client_session
-    except ImportError:
-        pytest.skip('mcp.shared.memory helper not available in this SDK version')
-
-    async with create_connected_server_and_client_session(
-            srv.mcp._mcp_server) as client:
+    async with _in_memory_client() as client:
         tools = await client.list_tools()
         names = {t.name for t in tools.tools}
         assert {'list_functions', 'describe', 'call', 'recommend_methods',
@@ -204,7 +208,8 @@ async def test_client_session_tools_and_resources():
         result = await client.call_tool(
             'call', {'name': 'gas.gas_z',
                      'arguments': {'p': 2000, 'sg': 0.75, 'degf': 200}})
-        assert not result.isError
+        # 2.x result fields are snake_case
+        assert not (result.is_error if srv._MCP_V2 else result.isError)
         assert '0.868265' in result.content[0].text
 
         resources = await client.list_resources()
@@ -230,3 +235,29 @@ def test_cli_parser_defaults_and_http():
                          '--host', '0.0.0.0', '--port', '9000'])
     assert (args.transport, args.host, args.port) == ('streamable-http',
                                                       '0.0.0.0', 9000)
+
+
+def test_main_passes_http_settings_to_the_sdk(monkeypatch):
+    """host, port and stateless_http reach the SDK: as run() keywords on
+    mcp 2.x, through mcp.settings on 1.x."""
+    calls = []
+    monkeypatch.setattr(srv.mcp, 'run', lambda **kw: calls.append(kw))
+    monkeypatch.setattr('sys.argv', ['pyrestoolbox-mcp', '--transport', 'streamable-http',
+                                     '--host', '0.0.0.0', '--port', '9000'])
+    srv.main()
+    want = {'host': '0.0.0.0', 'port': 9000, 'stateless_http': True}
+    if srv._MCP_V2:
+        assert calls == [dict(transport='streamable-http', **want)]
+    else:
+        assert calls == [{'transport': 'streamable-http'}]
+        assert {k: getattr(srv.mcp.settings, k) for k in want} == want
+    calls.clear()
+    monkeypatch.setattr('sys.argv', ['pyrestoolbox-mcp'])
+    srv.main()
+    assert calls == [{'transport': 'stdio'}]
+
+
+def test_sw_brine_props_helium():
+    out = srv.sw_brine_props(pres=3000, temp=150, ppm=50000, y_He=1.0)
+    assert out['x']['He'] > 0
+    assert out['bDen'][0] < out['bDen'][1]

{pyrestoolbox-3.8.2 → pyrestoolbox-3.8.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "pyrestoolbox"
-version = "3.8.2"
+version = "3.8.4"
 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.8.2 → pyrestoolbox-3.8.4}/pyrestoolbox/brine/_lib_salting_library.py

@@ -26,7 +26,7 @@ LN10 = np.log(10.0)  # 2.302585...
 # ====================================================================
 # Boiling points (K) for S&W gases
 TB_K = {
-    'H2': 20.3, 'N2': 77.4, 'CO2': 194.7, 'H2S': 212.8,  # H2S NBP 212.87 K (NIST)
+    'H2': 20.3, 'He': 4.2238, 'N2': 77.4, 'CO2': 194.7, 'H2S': 212.8,  # H2S NBP 212.87 K (NIST)
     'CH4': 111.6, 'C2H6': 184.6, 'C3H8': 231.1,
     'iC4H10': 261.4, 'nC4H10': 272.7, 'iC5H12': 301.0,
     'nC5H12': 309.2, 'nC6H14': 341.9, 'nC7H16': 371.6,

{pyrestoolbox-3.8.2 → pyrestoolbox-3.8.4}/pyrestoolbox/brine/_lib_vle_engine.py

@@ -106,6 +106,12 @@ COMPONENTS = {
     # Hydrogen (this work) - Uses Tc=33.145 K (NIST) consistently for both EOS and BIP correlations
     'H2': ComponentProperties('Hydrogen', 33.145, 1.2964e6, -0.219, 20.3, 2.016),
 
+    # Helium (He extension, 2026-10-02) - NIST constants (Ortiz-Vega et al. 2019 EOS critical
+    # point, as in CoolProp 8.0), used consistently for EOS and BIP correlations (Tr = T/5.1953).
+    # NOT the 5-component Z-factor model's helium Tc (a deliberately non-standard 6.35 degR, tuned
+    # for LBC dilute viscosity); the correlations below are valid only with these constants.
+    'He': ComponentProperties('Helium', 5.1953, 0.228323e6, -0.38354, 4.2238, 4.002602),
+
     # Acid gases
     'CO2': ComponentProperties('Carbon Dioxide', 304.2, 7.38e6, 0.2273, 194.7, 44.01),
     'H2S': ComponentProperties('Hydrogen Sulfide', 373.2, 8.94e6, 0.1081, 212.8, 34.082),
@@ -130,7 +136,7 @@ COMPONENTS = {
 # List of supported gas species (excludes water)
 GAS_SPECIES = ['H2', 'CO2', 'N2', 'H2S', 'CH4', 'C2H6', 'C3H8',
                'iC4H10', 'nC4H10', 'iC5H12', 'nC5H12',
-               'nC6H14', 'nC7H16', 'nC8H18', 'nC10H22']
+               'nC6H14', 'nC7H16', 'nC8H18', 'nC10H22', 'He']
 
 
 # =============================================================================
@@ -434,6 +440,16 @@ def kij_aq_h2_dropin(T_K: float, salinity_molal: float = 0.0) -> float:
     Tr = T_K / 33.145
     return (-14.9412 + Tr) / (2.2832 + 0.3893 * Tr)
 
+def kij_aq_he_dropin(T_K: float, salinity_molal: float = 0.0) -> float:
+    """He: rational, n=130, MAE=0.0183 (S&W alpha; He extension 2026-10-02).
+
+    Fitted L1 to fugacity-targeted pointwise kij from Gardiner & Smith 1972, Gerth 1983,
+    Abrosimov & Lebedeva 2013 (50-80 C), Pray et al. 1952 (163 C) and Potter & Clynne 1978
+    (104, 149 C); data 20-163 C, 1-1000 bar. Not validated above 200 C.
+    """
+    Tr = T_K / 5.1953
+    return (-71.6152 + Tr) / (-0.394962 + 0.505807 * Tr)
+
 def kij_aq_ch4_dropin(T_K: float, salinity_molal: float = 0.0) -> float:
     """CH4: rational, n=115, MAE=0.0089 (S&W alpha)."""
     Tr = T_K / 190.60
@@ -466,6 +482,7 @@ def _kij_aq_hc_proposed(gas: str):
 # Proposed: MC-3 alpha + freshwater-only kij. Salinity via Sechenov/gamma-phi.
 KIJ_AQ_MC3: Dict[str, Callable] = {
     'H2': kij_aq_h2_proposed,
+    'He': kij_aq_he_dropin,          # Default-framework fit, not refitted on MC-3 alpha
     'CO2': kij_aq_co2_proposed,
     'N2': kij_aq_n2_proposed,
     'H2S': kij_aq_h2s_proposed,
@@ -485,6 +502,7 @@ KIJ_AQ_MC3: Dict[str, Callable] = {
 # S&W original: S&W alpha + embedded salinity in kij for HC/CO2/N2.
 KIJ_AQ_SW_ORIGINAL: Dict[str, Callable] = {
     'H2': kij_aq_h2,                # Paper 1 rational (S&W had no H2)
+    'He': kij_aq_he_dropin,         # He extension (S&W had no He)
     'CO2': kij_aq_co2,              # S&W Eq 14 (embedded salinity)
     'N2': kij_aq_n2,                # S&W Eq 13 (embedded salinity)
     'H2S': kij_aq_h2s,              # S&W Eq 15 (no salinity)
@@ -504,6 +522,7 @@ KIJ_AQ_SW_ORIGINAL: Dict[str, Callable] = {
 # Drop-in: S&W alpha + freshwater-only kij refitted for S&W alpha + embedded delta.
 KIJ_AQ_DEFAULT: Dict[str, Callable] = {
     'H2': kij_aq_h2_dropin,
+    'He': kij_aq_he_dropin,
     'CO2': kij_aq_co2_dropin,
     'N2': kij_aq_n2_dropin,
     'H2S': kij_aq_h2s_dropin,
@@ -536,6 +555,7 @@ EMBEDDED_SALINITY_PARAMS_MC3 = {
     'CH4':    {'Tc': 190.60, 'a0': 0.1383, 'a1': -0.1394, 'a2': 0.0442},
     'N2':     {'Tc': 126.10, 'a0': 0.2257, 'a1': -0.1548, 'a2': 0.0321},
     'H2':     {'Tc': 33.145, 'a0': 0.3833, 'a1': -0.0660, 'a2': 0.0033},
+    'He':     {'Tc': 5.1953, 'a0': 0.359923, 'a1': -0.0095344, 'a2': 7.00398e-05},  # From default (not refitted)
     'C2H6':   {'Tc': 305.40, 'a0': 0.0791, 'a1': -0.1263, 'a2': 0.0677},
     'C3H8':   {'Tc': 369.80, 'a0': 0.0606, 'a1': -0.1165, 'a2': 0.0772},
     'nC4H10': {'Tc': 425.20, 'a0': 0.0488, 'a1': -0.1072, 'a2': 0.0836},
@@ -551,6 +571,7 @@ EMBEDDED_SALINITY_PARAMS_DEFAULT: Dict[str, Dict] = {
     'CH4':  {'Tc': 190.60, 'a0': 0.1304, 'a1': -0.1295, 'a2': 0.0394},
     'N2':   {'Tc': 126.10, 'a0': 0.2173, 'a1': -0.1468, 'a2': 0.0302},
     'H2':   {'Tc': 33.145, 'a0': 0.3658, 'a1': -0.0625, 'a2': 0.0030},
+    'He':   {'Tc': 5.1953, 'a0': 0.359923, 'a1': -0.0095344, 'a2': 7.00398e-05},  # He extension 2026-10-02: Sechenov target S&W Eq 8 (Tb 4.2238 K), 25-100 C
     'C2H6':   {'Tc': 305.40, 'a0': 0.0813, 'a1': -0.1287, 'a2': 0.0646},
     'C3H8':   {'Tc': 369.80, 'a0': 0.0606, 'a1': -0.1165, 'a2': 0.0772},  # From proposed (not refitted)
     'nC4H10': {'Tc': 425.20, 'a0': 0.0488, 'a1': -0.1072, 'a2': 0.0836},  # From proposed (not refitted)
@@ -668,6 +689,7 @@ def get_kij_aq(gas: str, T_K: float, salinity_molal: float = 0.0,
 # Constant kij_NA values from S&W 1992 Table 5
 KIJ_NA: Dict[str, Optional[float]] = {
     'H2': 0.468,       # This work
+    'He': 0.468,       # SURROGATE (He extension 2026-10-02): H2 value; no He water-content data found. Unvalidated.
     'CO2': 0.1896,     # S&W 1992 (or 0.18756 from Yan 2011)
     'N2': 0.4778,      # S&W 1992
     'H2S': 0.1610,     # This work (constant; replaces S&W Eq 17)
@@ -1534,78 +1556,44 @@ class SWBinaryVLE:
         """
         Calculate water mole fraction in gas phase using specified kij_NA.
 
+        Binary two-phase equilibrium by successive substitution on the K-values,
+        with the phase compositions fixed each pass by the binary closure
+        sum(K_i x_i) = sum(y_i) = 1:
+        x_w = (K_g - 1) / (K_g - K_w), y_w = K_w x_w. Before 3.8.3 the loop
+        normalised K x instead, which any x satisfies, so y_H2O came out as
+        K_w / (K_w + K_g x_g) with x_g wherever the iteration drifted; low by
+        roughly y_H2O itself (0.44 against 0.79 at 200 degF, 14.7 psia).
+
         Args:
             T_K: Temperature in Kelvin
             P_Pa: Pressure in Pascals
             kij_na: Binary interaction parameter for non-aqueous phase
             max_iter: Maximum iterations
 
-        Runs the successive substitution twice: the adaptive-damping pass
-        (canonical, preserves released behaviour) and a fixed-damping
-        verification pass. Near the dew boundary (high T, P within a few
-        multiples of Psat) the normalised iteration has multiple fixed
-        points; when the passes disagree by more than 0.5% relative the
-        answer is path-dependent and np.nan is returned instead of an
-        arbitrary branch. Non-convergence also returns np.nan.
-
         Returns:
-            y_H2O: Water mole fraction in gas phase (np.nan if the
-                   iteration fails to converge or is ambiguous)
+            y_H2O: Water mole fraction in gas phase; np.nan when no two-phase
+                   split exists (K_w >= 1 or K_g <= 1, e.g. at or below the
+                   water vapour pressure) or the iteration does not converge.
         """
-        y1, conv1 = self._water_content_ss(T_K, P_Pa, kij_na, max_iter,
-                                           adaptive=True)
-        if not conv1:
-            return np.nan
-        y2, conv2 = self._water_content_ss(T_K, P_Pa, kij_na, 2 * max_iter,
-                                           adaptive=False, damp=0.4)
-        if not conv2 or abs(y2 - y1) > 5e-3 * max(abs(y1), 1e-8):
-            return np.nan
-        return y1
+        y_w, converged = self._water_content_ss(T_K, P_Pa, kij_na, max_iter)
+        return y_w if converged else np.nan
 
     def _water_content_ss(self, T_K: float, P_Pa: float, kij_na: float,
-                          max_iter: int, adaptive: bool = True,
-                          damp: float = 0.3) -> Tuple[float, bool]:
-        """Damped successive substitution for water content. Returns (y_H2O, converged)."""
+                          max_iter: int) -> Tuple[float, bool]:
+        """Binary successive substitution for water content. Returns (y_H2O, converged)."""
         x = np.array([0.999, 0.001])
         y = np.array([0.02, 0.98])
-
-        prev_error = np.inf
-        for iteration in range(max_iter):
-            x = np.clip(x, 1e-14, 1.0 - 1e-14)
-            x = x / np.sum(x)
-            y = np.clip(y, 1e-14, 1.0 - 1e-14)
-            y = y / np.sum(y)
-
+        for _ in range(max_iter):
             K = self._calc_K_with_kij(T_K, P_Pa, x, y, kij_na)
-            if not np.all(np.isfinite(K)):
+            if not np.all(np.isfinite(K)) or K[0] >= 1.0 or K[1] <= 1.0:
                 return np.nan, False
-
-            y_new = K * x
-            y_new = np.clip(y_new, 1e-14, 1.0 - 1e-14)
-            y_new = y_new / np.sum(y_new)
-
-            error = np.max(np.abs(y_new - y))
-            if error < 1e-10:
+            x_w = (K[1] - 1.0) / (K[1] - K[0])
+            y_new = np.array([K[0] * x_w, 1.0 - K[0] * x_w])
+            converged = abs(y_new[0] - y[0]) < 1e-12 * max(y_new[0], 1e-8)
+            x = np.array([x_w, 1.0 - x_w])
+            y = y_new
+            if converged:
                 return y[0], True
-
-            if adaptive:
-                if error < prev_error:
-                    damp = min(damp * 1.15, 0.8)
-                else:
-                    damp = max(damp * 0.5, 0.1)
-                prev_error = error
-
-            y = y + damp * (y_new - y)
-            y = y / np.sum(y)
-
-            x_new = y / (K + 1e-30)
-            x_new = np.clip(x_new, 1e-14, 1.0 - 1e-14)
-            x_new = x_new / np.sum(x_new)
-            if x_new[0] < 0.5:
-                x_new = np.array([0.98, 0.02])
-            x = x + damp * (x_new - x)
-            x = x / np.sum(x)
-
         return y[0], False
 
     # Aliases for backward compatibility
@@ -1754,6 +1742,7 @@ _SW_KVALUE_PARAMS = {
     # Light gases: Cross form [a, b, c, d, e, f]
     # Fitted using proposed Burgoyne & Nielsen 2026 freshwater kij_AQ forms (Feb 2026)
     'H2':     [6.4295, 25.5844, -0.5985, -50.0000, -0.0007, -3.2598],
+    'He':     [9.7370, 50.0000, -1.0874, 50.0000, 0.0039, 10.0747],  # He extension 2026-10-02; b, d at bounds
     'CO2':    [-5.9974, 26.3804, -0.9380, -16.3941, 0.0607, 0.3688],
     'N2':     [1.4998, 36.4929, -0.6419, -50.0000, 0.0110, -0.6328],
     'H2S':    [-1.0549, 7.7334, -1.3646, -3.4035, 0.0850, 0.8651],
@@ -2053,6 +2042,23 @@ class SWMultiComponentFlash:
 
         return gamma
 
+    def _rust_matches(self, mode: str) -> bool:
+        """True if the Rust flash kernel computes what the Python path would.
+
+        The Rust 'default' kernel always adds the embedded delta_kij in AQ mode,
+        whereas the Python path adds it only for salinity_method='embedded'
+        (build_kij_matrix). Any other default pairing with salt present (e.g.
+        the class defaults, 'default' with 'gamma_phi') must take the Python
+        path: sending it to Rust put dissolved-gas x 30-50% apart between the
+        two paths at 2 m NaCl. 'mc3' matches for every salinity_method.
+        """
+        if self.framework == 'mc3':
+            return True
+        if self.framework != 'default':
+            return False
+        return (self.salinity_method == 'embedded' or self.salinity <= 0
+                or mode != 'AQ')
+
     def flash_tp(self, T_K: float, P_Pa: float, z: np.ndarray,
                  mode: str = 'AQ', gamma: Optional[np.ndarray] = None,
                  max_iter: int = 200,
@@ -2101,7 +2107,8 @@ class SWMultiComponentFlash:
         #
         # 'sw_original' has no Rust implementation and takes the Python path
         # rather than being silently downgraded.
-        if _RUST_AVAILABLE and self.framework in ('mc3', 'default'):
+        # See _rust_matches for which framework/salinity pairings qualify.
+        if _RUST_AVAILABLE and self._rust_matches(mode):
             try:
                 gamma_arr = np.asarray(gamma, dtype=float) if gamma is not None \
                     else np.ones(self.nc)
@@ -2485,6 +2492,7 @@ def calc_gas_brine_equilibrium(
     method: str = 'henry',
     salinity_method: str = 'gamma_phi',
     framework: str = 'default',
+    y_He: float = 0.0,
 ) -> Tuple[Dict[str, float], Dict[str, float]]:
     """
     Calculate gas-brine equilibrium using Soreide-Whitson framework.
@@ -2516,7 +2524,8 @@ def calc_gas_brine_equilibrium(
         salinity_wt_pct: Brine salinity in weight percent NaCl
         temperature_F: Temperature in degrees Fahrenheit
         pressure_psia: Pressure in psia
-        y_*: Mole fractions of each gas in dry gas (will be normalized)
+        y_*: Mole fractions of each gas in dry gas (will be normalized).
+             y_He is last in the signature so positional calls are unaffected.
         method: 'henry' (binary decomposition) or 'flash' (multi-component)
         salinity_method: 'gamma_phi', 'explicit', or 'embedded'
         framework: 'default', 'mc3', or 'sw_original' ('dropin' and
@@ -2539,16 +2548,10 @@ def calc_gas_brine_equilibrium(
     salinity_molal = wt_pct_to_molality(salinity_wt_pct)
 
     # Build gas composition dict
-    gas_comp = {}
-    if y_CH4 > 0: gas_comp['CH4'] = y_CH4
-    if y_C2H6 > 0: gas_comp['C2H6'] = y_C2H6
-    if y_C3H8 > 0: gas_comp['C3H8'] = y_C3H8
-    if y_nC4H10 > 0: gas_comp['nC4H10'] = y_nC4H10
-    if y_iC4H10 > 0: gas_comp['iC4H10'] = y_iC4H10
-    if y_CO2 > 0: gas_comp['CO2'] = y_CO2
-    if y_N2 > 0: gas_comp['N2'] = y_N2
-    if y_H2S > 0: gas_comp['H2S'] = y_H2S
-    if y_H2 > 0: gas_comp['H2'] = y_H2
+    gas_comp = {name: y for name, y in (
+        ('CH4', y_CH4), ('C2H6', y_C2H6), ('C3H8', y_C3H8), ('nC4H10', y_nC4H10),
+        ('iC4H10', y_iC4H10), ('CO2', y_CO2), ('N2', y_N2), ('H2S', y_H2S),
+        ('H2', y_H2), ('He', y_He)) if y > 0}
 
     if not gas_comp:
         raise ValueError("At least one gas component must have non-zero mole fraction")