pyrestoolbox 3.8.3__tar.gz → 3.8.5__tar.gz

{pyrestoolbox-3.8.3 → pyrestoolbox-3.8.5}/Cargo.lock

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

{pyrestoolbox-3.8.3 → pyrestoolbox-3.8.5}/Cargo.toml

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

{pyrestoolbox-3.8.3 → pyrestoolbox-3.8.5}/PKG-INFO

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

{pyrestoolbox-3.8.3 → pyrestoolbox-3.8.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "pyrestoolbox"
-version = "3.8.3"
+version = "3.8.5"
 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.3 → pyrestoolbox-3.8.5}/pyrestoolbox/classes/classes.py

@@ -25,7 +25,7 @@ Enum classes for method selection and class_dic registry.
 Enums
 -----
 z_method      Z-factor calculation method (DAK, HY, BNS)
-c_method      Critical property method (PMC, SUT, BUR, BNS)
+c_method      Critical property method (PMC, SUT, BNS)
 pb_method     Bubble point method (STAN, VALMC, VELAR)
 rs_method     Solution GOR method (VELAR, STAN, VALMC)
 bo_method     Oil FVF method (MCAIN, STAN)
@@ -60,8 +60,8 @@ class z_method(Enum):  # Gas Z-Factor calculation model
 class c_method(Enum):  # Gas critical properties calculation method
     PMC = 0
     SUT = 1
-    BUR = 2
     BNS = 3
+    BUR = 3  # Legacy alias for BNS
 
 class pb_method(Enum):  # Bubble point calculation method
     STAN = 0

{pyrestoolbox-3.8.3 → pyrestoolbox-3.8.5}/pyrestoolbox/docs/changelist.rst

@@ -1,3 +1,17 @@
+Changelist in 3.8.5:
+
+- **NODAL: gas VLP uses the ``gas_pvt`` Z-factor and viscosity methods (results move when a GasPVT is passed).** ``fbhp``, ``fthp``, ``outflow_curve``, ``operating_point`` and the simtools VFP tables took only the gas SG and Sutton/Wichert-Aziz pseudo-criticals from a ``GasPVT``; the march always ran Hall-Yarborough Z with Lee-Gonzalez-Eakin viscosity, so ``zmethod='BNS'`` (or the GasPVT default, DAK with PMC) was silently ignored, as were H2 and He (which raised a warning). The march now evaluates Z and viscosity exactly as ``gas_pvt.z()`` and ``gas_pvt.viscosity()`` do, at every step and in the zero-rate static column, in Python and Rust (the Rust march builds the same Z/viscosity evaluator as ``gas_dmp``, so every method stays accelerated; the two paths agree to 1e-9 relative). Calls without ``gas_pvt`` are bit-identical. Example (THP 1000 psia, 5 MMscf/d, 100 bbl/d water, 5000 ft of 2.441 in tubing, 80-200 degF, SG 0.65), Beggs-Brill BHP: 1475.3 psia before, 1459.3 with ``GasPVT(sg=0.65)`` (DAK/PMC), 1508.2 with ``zmethod='BNS'``; WG 1444.8, 1444.1, 1446.2. Beggs-Brill moves most because the distributed-to-segregated boundary sits mid-well here and the gradient steps 27% across it. The pure-Python fallback is about 15 times slower with a ``gas_pvt`` (about 40 ms per ``fbhp``), since each step calls ``gas_z`` and ``gas_ug``. No documented example passes a ``gas_pvt`` to the VLP functions, so none moves; one nodal test that asserted a sweet ``GasPVT`` equals the ``gsg``-only answer now compares an HY/SUT ``GasPVT`` (within 4e-5).
+
+- **NODAL: gas VLP results now approach the dry-gas answer continuously as the liquid rate goes to zero.** With no liquid every method returns the single-phase gas BHP, but a vanishing liquid rate did not: in a 5000 ft, 2.441 in well at 1000 psia THP and 5 MMscf/d (dry gas 1232 psia for all four methods), 1e-6 bbl/d of water gave WG 1294, GRAY 1243 and BB 1429 psia, and BB BHP fell as water rose from 0.001 to 1 bbl/d. The causes are in the correlations' low-liquid limits: the Woldesemayat-Ghajar drift-flux void fraction tends to u_sg/(u_sg + u_gm) because the drift velocity does not depend on the amount of liquid, leaving a stagnant liquid holdup u_gm/(u_sg + u_gm) at any liquid rate; Gray's holdup tends to exp(A); and Beggs-Brill holdup scales as lambda^0.58, so its friction parameter y = lambda/HL^2 grows without bound and the two-phase friction multiplier peaks near lambda = 1e-9. Hagedorn-Brown, whose holdup is floored at lambda, was already continuous. The gas segment march now blends each segment's gradient linearly between the method's own zero-liquid gradient and its two-phase gradient while the no-slip liquid fraction is below 1e-3 (``_LOW_LIQ_LAMBDA``, Rust ``LOW_LIQ_LAMBDA``). At zero liquid and at lambda >= 1e-3 results are unchanged; in between they are continuous and BHP rises monotonically with liquid rate. In the example, 1 bbl/d of water now gives WG 1237.5 (was 1298.5), GRAY 1233.3 (1245.8), BB 1241.2 (1335.7) and HB 1232.0 (1232.3) psia; 10 bbl/d gives WG 1300.8 (1312.7), GRAY 1263.3 (1269.2), BB 1324.9 (1338.9), HB 1234.7 (1235.3). Gas wells with a liquid-to-gas ratio above roughly 3 bbl/MMscf at flowing conditions, and every oil-well march, are unaffected. No frozen baseline or documented example moves.
+
+Changelist in 3.8.4:
+
+- **GAS: associated-gas hydrocarbon pseudo-criticals for BNS (``ag``).** Burgoyne, Nielsen & Stanko (2025) fitted two hydrocarbon Tc/Pc correlations, for gas condensates and for associated gas; only the condensate one was exposed. Every gas function that takes ``he`` (except ``gas_sg``, ``gas_hydrate`` and the recommenders, which use no critical properties) now also takes ``ag`` (keyword, appended last): ``gas_tc_pc``, ``gas_z``, ``gas_ug``, ``gas_cg``, ``gas_bg``, ``gas_den``, ``gas_thermal``, ``gas_ponz2p``, ``gas_grad2sg``, ``gas_dmp``, ``gas_rate_radial``, ``gas_rate_linear``, ``GasPVT`` and ``gas_matbal``. ``ag=True`` makes ``cmethod='BNS'`` return the associated-gas values (SG 0.75: Tc 397.7 against 401.2 degR, Pc 653.9 against 663.4 psia), and the hydrocarbon-inert BIPs follow the selected Tc, as in the regression. Other cmethods ignore it and a user ``tc``/``pc`` takes precedence. The resolved values reach the Rust paths through the existing hydrocarbon Tc/Pc override, so the Rust code is unchanged. With ``ag=True``, results match the reference BNS implementation (``AG=True``) to 5e-15 in Z and viscosity and 7e-13 Btu/lb-mol in enthalpy; with ``ag=False`` (the default) every result is bit-identical to 3.8.3 on both paths.
+
+- **GAS: BNS hydrocarbon SG floor aligned with the reference implementation (results move slightly in one corner).** When the inert fractions imply a hydrocarbon lighter than methane, the hydrocarbon SG is floored at methane. pyrestoolbox used 16.043/28.97 (Python and Rust) where the reference BNS code uses 16.0425/28.97, the methane MW of the method's own correlations. Both now use 16.0425/28.97. Only floored cases move (for SG 0.65 with 20% CO2, 10% H2S, 2% N2 and 10% H2: Z by up to 1.2e-5, viscosity 2.2e-5, enthalpy 1.4e-4 relative); everything else is bit-identical. With this, Python and Rust match the reference BNS implementation to about 1e-14 in Z and viscosity for every composition, with ``ag`` on or off.
+
+- **GAS: 'BNS' is the one documented name for the tuned Peng-Robinson method.** The docs and example notebooks used 'BUR' and 'BNS' interchangeably; they now use 'BNS' throughout. 'BUR' is still accepted as a silent alias for ``zmethod`` and ``cmethod``, and ``c_method.BUR`` is now an alias of ``c_method.BNS`` (it was a separate member that every code path treated as BNS), matching ``z_method``. Invalid-method errors list only canonical names. The ``gas_rate_radial`` and ``gas_rate_linear`` parameter tables now document ``h2`` and ``he``, and the stale ``'WYW'`` was dropped from the examples notebook's zmethod list.
+
 Changelist in 3.8.3:
 
 - **GAS: helium in the BNS Z-factor, viscosity and thermal model, in Python and Rust.** Every gas function that takes ``h2`` now also takes ``he`` (keyword, appended last so positional calls are unchanged): ``gas_z``, ``gas_ug``, ``gas_den``, ``gas_bg``, ``gas_cg``, ``gas_thermal``, ``gas_tc_pc``, ``gas_ponz2p``, ``gas_grad2sg``, ``gas_dmp``, ``gas_rate_radial``, ``gas_rate_linear``, ``gas_sg``, ``GasPVT``, ``gas_matbal``, ``gas_hydrate`` (water-content step only), ``recommend_gas_methods`` and ``recommend_methods``. Helium is a sixth BNS component with zero BIPs, regressed to 29,400 NIST points for pure helium (60-300 degF, 14.7-14,990 psia) with the LBC coefficients held: density 0.31% mean / 0.84% max, viscosity 0.70% / 3.1%. **Its critical temperature is a deliberately non-standard 6.35 degR (NIST 9.35 degR)**, because the BNS Tc also sets the Stiel-Thodos dilute viscosity, which is about 25% low at the true Tc; the docs carry a warning so it is not "corrected". A positive ``he`` forces BNS, as ``h2`` does. With ``he=0`` every result is unchanged (Rust within 3e-15, Python within 3e-15 except ``gas_cg``, whose finite-difference derivative moves by up to 8e-12); with helium, Python and Rust agree with the reference BNS implementation to about 1e-14 in Z and viscosity. The Rust ``gas_dmp_rust`` and ``gas_ponz2p_rust`` now take the inert fractions as one ``[co2, h2s, n2, h2, he]`` list (internal API). ``MW_HE`` (4.003, the BNS value) is added to ``constants``.

{pyrestoolbox-3.8.3 → pyrestoolbox-3.8.5}/pyrestoolbox/docs/examples.ipynb

@@ -19,8 +19,8 @@
     "Gas property calculations supporting hydrocarbon + impurity mixtures (CO2, H2S, N2, H2).\n",
     "\n",
     "### Calculation Methods\n",
-    "- **zmethod**: `'DAK'` (default), `'HY'`, `'WYW'`, `'BUR'`\n",
-    "- **cmethod**: `'PMC'` (default), `'SUT'`, `'BUR'`"
+    "- **zmethod**: `'DAK'` (default), `'HY'`, `'BNS'`\n",
+    "- **cmethod**: `'PMC'` (default), `'SUT'`, `'BNS'`"
    ]
   },
   {
@@ -64,7 +64,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "gas.gas_z(p=2350, sg=0.68, degf=180, co2=1.0, zmethod='BUR', cmethod='BUR')"
+    "gas.gas_z(p=2350, sg=0.68, degf=180, co2=1.0, zmethod='BNS', cmethod='BNS')"
    ]
   },
   {
@@ -82,7 +82,7 @@
    "source": [
     "gsg = gas.gas_sg(hc_mw=19.0, co2=0.05, h2s=0.10, n2=0, h2=0.20)\n",
     "print('Gas SG:', gsg)\n",
-    "gas.gas_z(p=2350, sg=gsg, degf=180, co2=0.05, h2s=0.10, n2=0, h2=0.20, zmethod='BUR', cmethod='BUR')"
+    "gas.gas_z(p=2350, sg=gsg, degf=180, co2=0.05, h2s=0.10, n2=0, h2=0.20, zmethod='BNS', cmethod='BNS')"
    ]
   },
   {
@@ -103,7 +103,7 @@
   },
   {
    "cell_type": "markdown",
-   "source": "### gas_sg - Mixture Gas Specific Gravity\n\nCalculate SG of a gas mixture containing impurities. Essential for BNS/BUR method inputs.",
+   "source": "### gas_sg - Mixture Gas Specific Gravity\n\nCalculate SG of a gas mixture containing impurities. Essential for BNS method inputs.",
    "metadata": {}
   },
   {
@@ -141,14 +141,14 @@
   },
   {
    "cell_type": "code",
-   "source": "# BUR critical properties for a gas with 10% CO2 and 5% H2S\ngas.gas_tc_pc(sg=0.75, co2=0.10, h2s=0.05, cmethod='BUR')",
+   "source": "# BNS critical properties for a gas with 10% CO2 and 5% H2S\ngas.gas_tc_pc(sg=0.75, co2=0.10, h2s=0.05, cmethod='BNS')",
    "metadata": {},
    "execution_count": null,
    "outputs": []
   },
   {
    "cell_type": "code",
-   "source": "# BUR auto-selects when H2 is present\ngas.gas_tc_pc(sg=0.6, h2=0.30)",
+   "source": "# BNS auto-selects when H2 is present\ngas.gas_tc_pc(sg=0.6, h2=0.30)",
    "metadata": {},
    "execution_count": null,
    "outputs": []
@@ -192,12 +192,12 @@
   },
   {
    "cell_type": "markdown",
-   "source": "BUR/BNS Z-Factor across a pressure range for different gas compositions. The BNS model uses a tuned 5-component Peng Robinson EOS that natively handles CO2, H2S, N2, and H2 at any concentration up to pure inerts.",
+   "source": "BNS Z-Factor across a pressure range for different gas compositions. The BNS model uses a tuned 5-component Peng Robinson EOS that natively handles CO2, H2S, N2, and H2 at any concentration up to pure inerts.",
    "metadata": {}
   },
   {
    "cell_type": "code",
-   "source": "import matplotlib.pyplot as plt\n\n# Compare Z-factor across pressures for different gas compositions using BUR\npressures = list(range(500, 10001, 500))\n\n# Pure methane (BUR)\nz_ch4 = gas.gas_z(p=pressures, sg=0.5539, degf=200, zmethod='BUR', cmethod='BUR')\n\n# 15% CO2 blend\nz_co2 = gas.gas_z(p=pressures, sg=0.7, degf=200, co2=0.15, zmethod='BUR', cmethod='BUR')\n\n# 20% H2 blend (auto-selects BUR)\nsg_h2 = gas.gas_sg(hc_mw=19.0, co2=0, h2s=0, n2=0, h2=0.20)\nz_h2 = gas.gas_z(p=pressures, sg=sg_h2, degf=200, h2=0.20, zmethod='BUR', cmethod='BUR')\n\n# Pure CO2\nz_pureco2 = gas.gas_z(p=pressures, sg=1.5196, degf=200, co2=1.0, zmethod='BUR', cmethod='BUR')\n\nplt.plot(pressures, z_ch4, label='Pure CH4')\nplt.plot(pressures, z_co2, label='15% CO2 blend')\nplt.plot(pressures, z_h2, label='20% H2 blend')\nplt.plot(pressures, z_pureco2, label='Pure CO2')\nplt.xlabel('Pressure (psia)')\nplt.ylabel('Z-Factor')\nplt.title('BNS Z-Factor: CO2 and H2 Blends')\nplt.legend()\nplt.grid(True)\nplt.show()",
+   "source": "import matplotlib.pyplot as plt\n\n# Compare Z-factor across pressures for different gas compositions using BNS\npressures = list(range(500, 10001, 500))\n\n# Pure methane (BNS)\nz_ch4 = gas.gas_z(p=pressures, sg=0.5539, degf=200, zmethod='BNS', cmethod='BNS')\n\n# 15% CO2 blend\nz_co2 = gas.gas_z(p=pressures, sg=0.7, degf=200, co2=0.15, zmethod='BNS', cmethod='BNS')\n\n# 20% H2 blend (auto-selects BNS)\nsg_h2 = gas.gas_sg(hc_mw=19.0, co2=0, h2s=0, n2=0, h2=0.20)\nz_h2 = gas.gas_z(p=pressures, sg=sg_h2, degf=200, h2=0.20, zmethod='BNS', cmethod='BNS')\n\n# Pure CO2\nz_pureco2 = gas.gas_z(p=pressures, sg=1.5196, degf=200, co2=1.0, zmethod='BNS', cmethod='BNS')\n\nplt.plot(pressures, z_ch4, label='Pure CH4')\nplt.plot(pressures, z_co2, label='15% CO2 blend')\nplt.plot(pressures, z_h2, label='20% H2 blend')\nplt.plot(pressures, z_pureco2, label='Pure CO2')\nplt.xlabel('Pressure (psia)')\nplt.ylabel('Z-Factor')\nplt.title('BNS Z-Factor: CO2 and H2 Blends')\nplt.legend()\nplt.grid(True)\nplt.show()",
    "metadata": {},
    "execution_count": null,
    "outputs": []
@@ -229,12 +229,12 @@
   },
   {
    "cell_type": "markdown",
-   "source": "BUR viscosity uses a tuned LBC (Lohrenz-Bray-Clark) method instead of the default Lee-Gonzalez-Eakin, enabling viscosity calculations for CO2-rich and H2-rich gases.",
+   "source": "BNS viscosity uses a tuned LBC (Lohrenz-Bray-Clark) method instead of the default Lee-Gonzalez-Eakin, enabling viscosity calculations for CO2-rich and H2-rich gases.",
    "metadata": {}
   },
   {
    "cell_type": "code",
-   "source": "# BUR/LBC viscosity for pure CO2\nprint('Pure CO2 viscosity:', gas.gas_ug(p=2000, sg=1.5196, degf=200, co2=1.0, zmethod='BUR', cmethod='BUR'))\n\n# Viscosity of a 20% H2 blend (BUR auto-selects)\nsg_h2mix = gas.gas_sg(hc_mw=19.0, co2=0, h2s=0, n2=0, h2=0.20)\nprint('20% H2 blend viscosity:', gas.gas_ug(p=2000, sg=sg_h2mix, degf=200, h2=0.20))\n\n# Viscosity comparison across pressure range for conventional vs H2 blend\npressures = list(range(500, 8001, 500))\nug_conv = gas.gas_ug(p=pressures, sg=0.7, degf=200)\nug_h2 = gas.gas_ug(p=pressures, sg=sg_h2mix, degf=200, h2=0.20, zmethod='BUR', cmethod='BUR')\nug_co2 = gas.gas_ug(p=pressures, sg=1.5196, degf=200, co2=1.0, zmethod='BUR', cmethod='BUR')\n\nplt.plot(pressures, ug_conv, label='Conventional gas (LEG)')\nplt.plot(pressures, ug_h2, label='20% H2 blend (LBC)')\nplt.plot(pressures, ug_co2, label='Pure CO2 (LBC)')\nplt.xlabel('Pressure (psia)')\nplt.ylabel('Viscosity (cP)')\nplt.title('Gas Viscosity: Conventional vs BNS/LBC Method')\nplt.legend()\nplt.grid(True)\nplt.show()",
+   "source": "# BNS/LBC viscosity for pure CO2\nprint('Pure CO2 viscosity:', gas.gas_ug(p=2000, sg=1.5196, degf=200, co2=1.0, zmethod='BNS', cmethod='BNS'))\n\n# Viscosity of a 20% H2 blend (BNS auto-selects)\nsg_h2mix = gas.gas_sg(hc_mw=19.0, co2=0, h2s=0, n2=0, h2=0.20)\nprint('20% H2 blend viscosity:', gas.gas_ug(p=2000, sg=sg_h2mix, degf=200, h2=0.20))\n\n# Viscosity comparison across pressure range for conventional vs H2 blend\npressures = list(range(500, 8001, 500))\nug_conv = gas.gas_ug(p=pressures, sg=0.7, degf=200)\nug_h2 = gas.gas_ug(p=pressures, sg=sg_h2mix, degf=200, h2=0.20, zmethod='BNS', cmethod='BNS')\nug_co2 = gas.gas_ug(p=pressures, sg=1.5196, degf=200, co2=1.0, zmethod='BNS', cmethod='BNS')\n\nplt.plot(pressures, ug_conv, label='Conventional gas (LEG)')\nplt.plot(pressures, ug_h2, label='20% H2 blend (LBC)')\nplt.plot(pressures, ug_co2, label='Pure CO2 (LBC)')\nplt.xlabel('Pressure (psia)')\nplt.ylabel('Viscosity (cP)')\nplt.title('Gas Viscosity: Conventional vs BNS/LBC Method')\nplt.legend()\nplt.grid(True)\nplt.show()",
    "metadata": {},
    "execution_count": null,
    "outputs": []
@@ -267,7 +267,7 @@
   },
   {
    "cell_type": "code",
-   "source": "# Gas compressibility for pure CO2 and H2 blend using BUR\nprint('Cg pure CO2:', gas.gas_cg(p=2000, sg=1.5196, degf=200, co2=1.0, zmethod='BUR', cmethod='BUR'))\n\nsg_h2 = gas.gas_sg(hc_mw=19.0, co2=0, h2s=0, n2=0, h2=0.20)\nprint('Cg 20% H2 blend:', gas.gas_cg(p=2000, sg=sg_h2, degf=200, h2=0.20, zmethod='BUR', cmethod='BUR'))",
+   "source": "# Gas compressibility for pure CO2 and H2 blend using BNS\nprint('Cg pure CO2:', gas.gas_cg(p=2000, sg=1.5196, degf=200, co2=1.0, zmethod='BNS', cmethod='BNS'))\n\nsg_h2 = gas.gas_sg(hc_mw=19.0, co2=0, h2s=0, n2=0, h2=0.20)\nprint('Cg 20% H2 blend:', gas.gas_cg(p=2000, sg=sg_h2, degf=200, h2=0.20, zmethod='BNS', cmethod='BNS'))",
    "metadata": {},
    "execution_count": null,
    "outputs": []
@@ -300,7 +300,7 @@
   },
   {
    "cell_type": "code",
-   "source": "# Bg for pure CO2 using BUR\nprint('Bg pure CO2:', gas.gas_bg(p=3000, sg=1.5196, degf=200, co2=1.0, zmethod='BUR', cmethod='BUR'))\n\n# Bg for 20% H2 blend\nsg_h2 = gas.gas_sg(hc_mw=19.0, co2=0, h2s=0, n2=0, h2=0.20)\nprint('Bg 20% H2 blend:', gas.gas_bg(p=3000, sg=sg_h2, degf=200, h2=0.20, zmethod='BUR', cmethod='BUR'))",
+   "source": "# Bg for pure CO2 using BNS\nprint('Bg pure CO2:', gas.gas_bg(p=3000, sg=1.5196, degf=200, co2=1.0, zmethod='BNS', cmethod='BNS'))\n\n# Bg for 20% H2 blend\nsg_h2 = gas.gas_sg(hc_mw=19.0, co2=0, h2s=0, n2=0, h2=0.20)\nprint('Bg 20% H2 blend:', gas.gas_bg(p=3000, sg=sg_h2, degf=200, h2=0.20, zmethod='BNS', cmethod='BNS'))",
    "metadata": {},
    "execution_count": null,
    "outputs": []
@@ -323,7 +323,7 @@
   },
   {
    "cell_type": "code",
-   "source": "# Gas density for pure CO2 using BUR\nprint('Pure CO2 density:', gas.gas_den(p=2000, sg=1.5196, degf=200, co2=1.0, zmethod='BUR', cmethod='BUR'))\n\n# Gas density for 20% H2 blend - much lighter than conventional gas\nsg_h2 = gas.gas_sg(hc_mw=19.0, co2=0, h2s=0, n2=0, h2=0.20)\nprint('20% H2 blend density:', gas.gas_den(p=2000, sg=sg_h2, degf=200, h2=0.20, zmethod='BUR', cmethod='BUR'))\n\n# Conventional gas density for comparison\nprint('Conventional gas density:', gas.gas_den(p=2000, sg=0.75, degf=200))",
+   "source": "# Gas density for pure CO2 using BNS\nprint('Pure CO2 density:', gas.gas_den(p=2000, sg=1.5196, degf=200, co2=1.0, zmethod='BNS', cmethod='BNS'))\n\n# Gas density for 20% H2 blend - much lighter than conventional gas\nsg_h2 = gas.gas_sg(hc_mw=19.0, co2=0, h2s=0, n2=0, h2=0.20)\nprint('20% H2 blend density:', gas.gas_den(p=2000, sg=sg_h2, degf=200, h2=0.20, zmethod='BNS', cmethod='BNS'))\n\n# Conventional gas density for comparison\nprint('Conventional gas density:', gas.gas_den(p=2000, sg=0.75, degf=200))",
    "metadata": {},
    "execution_count": null,
    "outputs": []
@@ -414,7 +414,7 @@
   },
   {
    "cell_type": "code",
-   "source": "# Pseudopressure for pure CO2 using BUR\nprint('dmp pure CO2:', gas.gas_dmp(p1=1000, p2=3000, degf=200, sg=1.5196, co2=1.0, zmethod='BUR', cmethod='BUR'))\n\n# Pseudopressure for 20% H2 blend (BUR auto-selects)\nsg_h2 = gas.gas_sg(hc_mw=19.0, co2=0, h2s=0, n2=0, h2=0.20)\nprint('dmp 20% H2 blend:', gas.gas_dmp(p1=1000, p2=3000, degf=200, sg=sg_h2, h2=0.20))",
+   "source": "# Pseudopressure for pure CO2 using BNS\nprint('dmp pure CO2:', gas.gas_dmp(p1=1000, p2=3000, degf=200, sg=1.5196, co2=1.0, zmethod='BNS', cmethod='BNS'))\n\n# Pseudopressure for 20% H2 blend (BNS auto-selects)\nsg_h2 = gas.gas_sg(hc_mw=19.0, co2=0, h2s=0, n2=0, h2=0.20)\nprint('dmp 20% H2 blend:', gas.gas_dmp(p1=1000, p2=3000, degf=200, sg=sg_h2, h2=0.20))",
    "metadata": {},
    "execution_count": null,
    "outputs": []
@@ -463,7 +463,7 @@
   },
   {
    "cell_type": "code",
-   "source": "# Radial gas flow rate for pure CO2 using BUR\nprint('Pure CO2 rate:', gas.gas_rate_radial(\n    k=5, h=50, pr=2000, pwf=750, r_w=0.3, r_ext=1500, degf=180,\n    sg=1.5196, co2=1.0, zmethod='BUR', cmethod='BUR', D=0.01, S=5\n))\n\n# Radial gas flow rate for 20% H2 blend\nsg_h2 = gas.gas_sg(hc_mw=19.0, co2=0, h2s=0, n2=0, h2=0.20)\nprint('20% H2 blend rate:', gas.gas_rate_radial(\n    k=5, h=50, pr=2000, pwf=750, r_w=0.3, r_ext=1500, degf=180,\n    sg=sg_h2, h2=0.20, zmethod='BUR', cmethod='BUR', D=0.01, S=5\n))",
+   "source": "# Radial gas flow rate for pure CO2 using BNS\nprint('Pure CO2 rate:', gas.gas_rate_radial(\n    k=5, h=50, pr=2000, pwf=750, r_w=0.3, r_ext=1500, degf=180,\n    sg=1.5196, co2=1.0, zmethod='BNS', cmethod='BNS', D=0.01, S=5\n))\n\n# Radial gas flow rate for 20% H2 blend\nsg_h2 = gas.gas_sg(hc_mw=19.0, co2=0, h2s=0, n2=0, h2=0.20)\nprint('20% H2 blend rate:', gas.gas_rate_radial(\n    k=5, h=50, pr=2000, pwf=750, r_w=0.3, r_ext=1500, degf=180,\n    sg=sg_h2, h2=0.20, zmethod='BNS', cmethod='BNS', D=0.01, S=5\n))",
    "metadata": {},
    "execution_count": null,
    "outputs": []
@@ -496,7 +496,7 @@
   },
   {
    "cell_type": "code",
-   "source": "# Linear gas flow rate for pure CO2 using BUR\nprint('Pure CO2 linear rate:', gas.gas_rate_linear(\n    k=0.1, area=50, length=200, pr=2000, pwf=250, degf=180,\n    sg=1.5196, co2=1.0, zmethod='BUR', cmethod='BUR'\n))\n\n# Linear gas flow rate for 20% H2 blend\nsg_h2 = gas.gas_sg(hc_mw=19.0, co2=0, h2s=0, n2=0, h2=0.20)\nprint('20% H2 blend linear rate:', gas.gas_rate_linear(\n    k=0.1, area=50, length=200, pr=2000, pwf=250, degf=180,\n    sg=sg_h2, h2=0.20, zmethod='BUR', cmethod='BUR'\n))",
+   "source": "# Linear gas flow rate for pure CO2 using BNS\nprint('Pure CO2 linear rate:', gas.gas_rate_linear(\n    k=0.1, area=50, length=200, pr=2000, pwf=250, degf=180,\n    sg=1.5196, co2=1.0, zmethod='BNS', cmethod='BNS'\n))\n\n# Linear gas flow rate for 20% H2 blend\nsg_h2 = gas.gas_sg(hc_mw=19.0, co2=0, h2s=0, n2=0, h2=0.20)\nprint('20% H2 blend linear rate:', gas.gas_rate_linear(\n    k=0.1, area=50, length=200, pr=2000, pwf=250, degf=180,\n    sg=sg_h2, h2=0.20, zmethod='BNS', cmethod='BNS'\n))",
    "metadata": {},
    "execution_count": null,
    "outputs": []

{pyrestoolbox-3.8.3 → pyrestoolbox-3.8.5}/pyrestoolbox/docs/gas.rst

@@ -22,7 +22,7 @@ pyResToolBox uses class objects to track calculation options through the functio
 
        + 'DAK': Dranchuk & Abou-Kassem (1975) using from Equations 2.7-2.8 from 'Petroleum Reservoir Fluid Property Correlations' by W. McCain et al. - Slowest, Most Accurate
        + 'HY': Hall & Yarborough (1973) - Second Fastest
-       + 'BUR'/'BNS': Tuned Peng Robinson EOS model, Burgoyne, Nielsen & Stanko (2025), `SPE-229932-MS <https://doi.org/10.2118/229932-MS>`_, extended with helium in 3.8.3 - Fast, reliable, and able to handle wide range of mixture types including CO2, H2S, N2, H2 and He at concentrations up to pure inerts. More information about the method can be found `here <https://github.com/mwburgoyne/5_Component_PengRobinson_Z-Factor>`_
+       + 'BNS': Tuned Peng Robinson EOS model, Burgoyne, Nielsen & Stanko (2025), `SPE-229932-MS <https://doi.org/10.2118/229932-MS>`_, extended with helium in 3.8.3 - Fast, reliable, and able to handle wide range of mixture types including CO2, H2S, N2, H2 and He at concentrations up to pure inerts. More information about the method can be found `here <https://github.com/mwburgoyne/5_Component_PengRobinson_Z-Factor>`_
    * - cmethod
      - c_method
      - Method for calculating gas critical properties. Defaults to 'PMC' 
@@ -30,7 +30,7 @@ pyResToolBox uses class objects to track calculation options through the functio
 
        + 'SUT': Sutton with Wichert & Aziz non-hydrocarbon corrections
        + 'PMC': Piper, McCain & Corredor (1999) correlation, using equations 2.4 - 2.6 from 'Petroleum Reservoir Fluid Property Correlations' by W. McCain et al.
-       + 'BUR': Correlation tuned to return the critical properties of the pure hydrocarbon component of a mixture, required for the 'BUR' (tuned Peng Robinson) Z-Factor method. More information about the method can be found `here <https://github.com/mwburgoyne/5_Component_PengRobinson_Z-Factor>`_
+       + 'BNS': Correlation tuned to return the critical properties of the pure hydrocarbon component of a mixture, required for the 'BNS' (tuned Peng Robinson) Z-Factor method. Gas-condensate correlation by default; set ``ag=True`` for the associated-gas correlation (see *Associated gas in BNS*). More information about the method can be found `here <https://github.com/mwburgoyne/5_Component_PengRobinson_Z-Factor>`_
    * - hydmethod
      - hyd_method
      - Method for calculating gas hydrate formation temperature. Defaults to 'TOWLER'.
@@ -77,6 +77,16 @@ Calculating gas Z-Factor of pure methane using DAK and PMC for critical properti
    - **SUT / PMC**: ``tc`` and ``pc`` are the *mixture* pseudo-critical values. They replace the correlation output entirely.
    - **BNS**: ``tc`` and ``pc`` are the *inert-free hydrocarbon* pseudo-critical values. They replace only the hydrocarbon pseudo-component in the EOS; inert Tc/Pc (CO2, H2S, N2, H2, He) remain the BNS internal per-component constants.
 
+Associated gas in BNS
+---------------------
+
+BNS characterises the hydrocarbon part of the gas as one pseudo-component whose Tc and Pc come from the hydrocarbon specific gravity. Burgoyne, Nielsen & Stanko (2025) fitted two such correlations: one for gas condensates (the default) and one for associated gas, which gives a lower Pc at every specific gravity and a Tc within about 1.5% of the condensate value (lower below a hydrocarbon SG of about 1.2, higher above). Set ``ag=True`` to use the associated-gas correlation. It applies only with ``cmethod='BNS'`` and is ignored by other methods; a user-supplied ``tc`` or ``pc`` takes precedence. The hydrocarbon-inert binary interaction parameters are functions of the hydrocarbon Tc, so they follow the selected correlation, as in the regression behind the method. Results match the reference implementation (``AG=True`` in the `5_Component_PengRobinson_Z-Factor <https://github.com/mwburgoyne/5_Component_PengRobinson_Z-Factor>`_ repository) to about 1e-14 in Z and viscosity.
+
+    >>> gas.gas_tc_pc(sg=0.75, cmethod='BNS')
+    (401.2348975509288, 663.436579436262)
+    >>> gas.gas_tc_pc(sg=0.75, cmethod='BNS', ag=True)
+    (397.7239050745307, 653.8703430787151)
+
 Helium in BNS
 ~~~~~~~~~~~~~
 
@@ -126,7 +136,7 @@ Calculating gas Z-Factor of pure CO2
 
 .. code-block:: python
 
-    >>> gas.gas_z(p=2350, sg=0.68, degf = 180, co2 = 1.0, zmethod='BUR', cmethod='BUR')
+    >>> gas.gas_z(p=2350, sg=0.68, degf = 180, co2 = 1.0, zmethod='BNS', cmethod='BNS')
     0.5258309021348752
     
 Calculating gas sg, and then gas Z-Factor of a mixture of 5% CO2, 10% H2S, 0% N2 and 20% H2 (remainder natural gas with MW = 19).
@@ -134,7 +144,7 @@ Calculating gas sg, and then gas Z-Factor of a mixture of 5% CO2, 10% H2S, 0% N2
 .. code-block:: python
 
     >>> gsg = gas.gas_sg(hc_mw = 19.0, co2 = 0.05, h2s = 0.10, n2 = 0, h2 = 0.20)
-    >>> gas.gas_z(p=2350, sg=gsg, degf = 180, co2 = 0.05, h2s = 0.10, n2 = 0, h2 = 0.20, zmethod='BUR', cmethod='BUR')
+    >>> gas.gas_z(p=2350, sg=gsg, degf = 180, co2 = 0.05, h2s = 0.10, n2 = 0, h2 = 0.20, zmethod='BNS', cmethod='BNS')
     0.9048153036714465
 
 
@@ -234,10 +244,13 @@ For ``cmethod='BNS'``, the returned values describe the *inert-free hydrocarbon*
      - Molar fraction of Nitrogen. Defaults to zero if undefined 
    * - h2
      - float
-     - Molar fraction of Hydrogen. Defaults to zero if undefined. If positive fraction, cmethod will override to 'BUR'
+     - Molar fraction of Hydrogen. Defaults to zero if undefined. If positive fraction, cmethod will override to 'BNS'
    * - he
      - float
      - Molar fraction of Helium. Defaults to 0. Keyword, last in the signature (new in 3.8.3). Like h2, a positive fraction forces zmethod and cmethod to 'BNS'; see *Helium in BNS*
+   * - ag
+     - bool
+     - BNS only. If True, the hydrocarbon pseudo-component Tc and Pc come from the associated-gas correlation instead of the default gas-condensate one; see *Associated gas in BNS*. Defaults to False. Keyword, last in the signature (new in 3.8.4). User-supplied tc/pc take precedence
    * - cmethod
      - string or c_method
      - Method for calculating gas critical parameters. `Calculation Methods and Class Objects`_.
@@ -326,10 +339,13 @@ A float or list / array can be used for p, returning corresponding 1-D array of
      - Molar fraction of Nitrogen. Defaults to zero if undefined
    * - h2
      - float
-     - Molar fraction of Hydrogen. Defaults to zero if undefined. zmethod and cmethod get overriden to 'BUR' if positive fraction.
+     - Molar fraction of Hydrogen. Defaults to zero if undefined. zmethod and cmethod get overridden to 'BNS' if positive fraction.
    * - he
      - float
      - Molar fraction of Helium. Defaults to 0. Keyword, last in the signature (new in 3.8.3). Like h2, a positive fraction forces zmethod and cmethod to 'BNS'; see *Helium in BNS*
+   * - ag
+     - bool
+     - BNS only. If True, the hydrocarbon pseudo-component Tc and Pc come from the associated-gas correlation instead of the default gas-condensate one; see *Associated gas in BNS*. Defaults to False. Keyword, last in the signature (new in 3.8.4). User-supplied tc/pc take precedence
    * - tc
      - float
      - Critical gas temperature (deg R, or K if metric=True). Uses cmethod correlation if not specified. For BNS, overrides only the hydrocarbon pseudo-component Tc (inert Tc stay at BNS internal constants)
@@ -371,7 +387,7 @@ pyrestoolbox.gas.gas_ug
 
     gas_ug(p, sg, degf, zmethod ='DAK', cmethod = 'PMC', co2 = 0, h2s = 0, n2 = 0, h2 = 0, tc = 0, pc = 0, zee = 0, ugz = False, metric = False, he = 0) -> float or np.array
 
-Returns gas viscosity (cP) using Lee, Gonzalez & Eakin (1966) correlation unless the 'BUR' method for Z-Factor is selected in which case a tuned LBC method is used. 
+Returns gas viscosity (cP) using Lee, Gonzalez & Eakin (1966) correlation unless the 'BNS' method for Z-Factor is selected in which case a tuned LBC method is used. 
 A float or list / array can be used for p, returning corresponding 1-D array of gas viscosities. The cmethod will be used to calculate critical gas parameters unless tc and/or pc are explicitly set to be non-zero. This option enables users to use pre-calculate gas critical properties and so avoid repeated duplicated critical property calculations when compute time is an issue
 Furnishing a positive value for zee means it will be used instead of calculating Z, and setting ugz to True will return the viscosity * Z product instead of viscosity alone
 
@@ -409,10 +425,13 @@ Furnishing a positive value for zee means it will be used instead of calculating
      - Molar fraction of Nitrogen. Defaults to zero if undefined
    * - h2
      - float
-     - Molar fraction of Hydrogen. Defaults to zero if undefined. Overrides methods to 'BUR' if positive fraction.
+     - Molar fraction of Hydrogen. Defaults to zero if undefined. Overrides methods to 'BNS' if positive fraction.
    * - he
      - float
      - Molar fraction of Helium. Defaults to 0. Keyword, last in the signature (new in 3.8.3). Like h2, a positive fraction forces zmethod and cmethod to 'BNS'; see *Helium in BNS*
+   * - ag
+     - bool
+     - BNS only. If True, the hydrocarbon pseudo-component Tc and Pc come from the associated-gas correlation instead of the default gas-condensate one; see *Associated gas in BNS*. Defaults to False. Keyword, last in the signature (new in 3.8.4). User-supplied tc/pc take precedence
    * - tc
      - float
      - Critical gas temperature (deg R, or K if metric=True). Uses cmethod correlation if not specified. For BNS, overrides only the hydrocarbon pseudo-component Tc (inert Tc stay at BNS internal constants)
@@ -492,10 +511,13 @@ A float or list / array can be used for p, returning corresponding 1-D array of
      - Molar fraction of Nitrogen. Defaults to zero if undefined
    * - h2
      - float
-     - Molar fraction of Hydrogen. Defaults to zero if undefined. If positive fraction, cmethod will override to 'BUR'
+     - Molar fraction of Hydrogen. Defaults to zero if undefined. If positive fraction, cmethod will override to 'BNS'
    * - he
      - float
      - Molar fraction of Helium. Defaults to 0. Keyword, last in the signature (new in 3.8.3). Like h2, a positive fraction forces zmethod and cmethod to 'BNS'; see *Helium in BNS*
+   * - ag
+     - bool
+     - BNS only. If True, the hydrocarbon pseudo-component Tc and Pc come from the associated-gas correlation instead of the default gas-condensate one; see *Associated gas in BNS*. Defaults to False. Keyword, last in the signature (new in 3.8.4). User-supplied tc/pc take precedence
    * - tc
      - float
      - Critical gas temperature (deg R, or K if metric=True). Uses cmethod correlation if not specified. For BNS, overrides only the hydrocarbon pseudo-component Tc (inert Tc stay at BNS internal constants)
@@ -572,10 +594,13 @@ A float or list / array can be used for p, returning corresponding 1-D array of
      - Molar fraction of Nitrogen. Defaults to zero if undefined
    * - h2
      - float
-     - Molar fraction of Hydrogen. Defaults to zero if undefined. If positive fraction, cmethod will override to 'BUR'
+     - Molar fraction of Hydrogen. Defaults to zero if undefined. If positive fraction, cmethod will override to 'BNS'
    * - he
      - float
      - Molar fraction of Helium. Defaults to 0. Keyword, last in the signature (new in 3.8.3). Like h2, a positive fraction forces zmethod and cmethod to 'BNS'; see *Helium in BNS*
+   * - ag
+     - bool
+     - BNS only. If True, the hydrocarbon pseudo-component Tc and Pc come from the associated-gas correlation instead of the default gas-condensate one; see *Associated gas in BNS*. Defaults to False. Keyword, last in the signature (new in 3.8.4). User-supplied tc/pc take precedence
    * - tc
      - float
      - Critical gas temperature (deg R, or K if metric=True). Uses cmethod correlation if not specified. For BNS, overrides only the hydrocarbon pseudo-component Tc (inert Tc stay at BNS internal constants)
@@ -651,10 +676,13 @@ A float or list / array can be used for p, returning corresponding 1-D array of
      - Molar fraction of Nitrogen. Defaults to zero if undefined
    * - h2
      - float
-     - Molar fraction of Hydrogen. Defaults to zero if undefined. If positive fraction, cmethod will override to 'BUR'
+     - Molar fraction of Hydrogen. Defaults to zero if undefined. If positive fraction, cmethod will override to 'BNS'
    * - he
      - float
      - Molar fraction of Helium. Defaults to 0. Keyword, last in the signature (new in 3.8.3). Like h2, a positive fraction forces zmethod and cmethod to 'BNS'; see *Helium in BNS*
+   * - ag
+     - bool
+     - BNS only. If True, the hydrocarbon pseudo-component Tc and Pc come from the associated-gas correlation instead of the default gas-condensate one; see *Associated gas in BNS*. Defaults to False. Keyword, last in the signature (new in 3.8.4). User-supplied tc/pc take precedence
    * - tc
      - float
      - Critical gas temperature (deg R, or K if metric=True). Uses cmethod correlation if not specified. For BNS, overrides only the hydrocarbon pseudo-component Tc (inert Tc stay at BNS internal constants)
@@ -742,6 +770,9 @@ Departure enthalpy for lean hydrocarbon gas carries a systematic bias of about
    * - he
      - float
      - Molar fraction of Helium. Defaults to 0. Keyword, last in the signature (new in 3.8.3). Like h2, a positive fraction forces zmethod and cmethod to 'BNS'; see *Helium in BNS*
+   * - ag
+     - bool
+     - BNS only. If True, the hydrocarbon pseudo-component Tc and Pc come from the associated-gas correlation instead of the default gas-condensate one; see *Associated gas in BNS*. Defaults to False. Keyword, last in the signature (new in 3.8.4). User-supplied tc/pc take precedence
    * - tc
      - float
      - Overrides the hydrocarbon pseudo-component Tc (deg R, or K if metric=True). Inert Tc stay at BNS internal constants
@@ -890,10 +921,13 @@ A float or list / array can be used for poverz, returning corresponding 1-D arra
      - Molar fraction of Nitrogen. Defaults to zero if undefined
    * - h2
      - float
-     - Molar fraction of Hydrogen. Defaults to zero if undefined. If positive fraction, cmethod will override to 'BUR'
+     - Molar fraction of Hydrogen. Defaults to zero if undefined. If positive fraction, cmethod will override to 'BNS'
    * - he
      - float
      - Molar fraction of Helium. Defaults to 0. Keyword, last in the signature (new in 3.8.3). Like h2, a positive fraction forces zmethod and cmethod to 'BNS'; see *Helium in BNS*
+   * - ag
+     - bool
+     - BNS only. If True, the hydrocarbon pseudo-component Tc and Pc come from the associated-gas correlation instead of the default gas-condensate one; see *Associated gas in BNS*. Defaults to False. Keyword, last in the signature (new in 3.8.4). User-supplied tc/pc take precedence
    * - tc
      - float
      - Critical gas temperature (deg R, or K if metric=True). Uses cmethod correlation if not specified. For BNS, overrides only the hydrocarbon pseudo-component Tc (inert Tc stay at BNS internal constants)
@@ -970,10 +1004,13 @@ Returns gas specific gravity consistent with observed gas gradient. Calculated t
      - Molar fraction of Nitrogen. Defaults to zero if undefined
    * - h2
      - float
-     - Molar fraction of Hydrogen. Defaults to zero if undefined. If positive fraction, cmethod will override to 'BUR'
+     - Molar fraction of Hydrogen. Defaults to zero if undefined. If positive fraction, cmethod will override to 'BNS'
    * - he
      - float
      - Molar fraction of Helium. Defaults to 0. Keyword, last in the signature (new in 3.8.3). Like h2, a positive fraction forces zmethod and cmethod to 'BNS'; see *Helium in BNS*
+   * - ag
+     - bool
+     - BNS only. If True, the hydrocarbon pseudo-component Tc and Pc come from the associated-gas correlation instead of the default gas-condensate one; see *Associated gas in BNS*. Defaults to False. Keyword, last in the signature (new in 3.8.4). User-supplied tc/pc take precedence
    * - tc
      - float
      - Critical gas temperature (deg R, or K if metric=True). Uses cmethod correlation if not specified. For BNS, overrides only the hydrocarbon pseudo-component Tc (inert Tc stay at BNS internal constants)
@@ -1052,10 +1089,13 @@ Integrates the equation: m(p) = 2 * p / (ug * z)
      - Molar fraction of Nitrogen. Defaults to zero if undefined
    * - h2
      - float
-     - Molar fraction of Hydrogen. Defaults to zero if undefined. If positive fraction, cmethod will override to 'BUR'
+     - Molar fraction of Hydrogen. Defaults to zero if undefined. If positive fraction, cmethod will override to 'BNS'
    * - he
      - float
      - Molar fraction of Helium. Defaults to 0. Keyword, last in the signature (new in 3.8.3). Like h2, a positive fraction forces zmethod and cmethod to 'BNS'; see *Helium in BNS*
+   * - ag
+     - bool
+     - BNS only. If True, the hydrocarbon pseudo-component Tc and Pc come from the associated-gas correlation instead of the default gas-condensate one; see *Associated gas in BNS*. Defaults to False. Keyword, last in the signature (new in 3.8.4). User-supplied tc/pc take precedence
    * - tc
      - float
      - Critical gas temperature (deg R, or K if metric=True). Uses cmethod correlation if not specified. For BNS, overrides only the hydrocarbon pseudo-component Tc (inert Tc stay at BNS internal constants)
@@ -1197,6 +1237,9 @@ A ``gas_pvt`` object can be provided instead of individual gas composition param
    * - h2s
      - float
      - Molar fraction of H2S. Defaults to zero if undefined
+   * - h2
+     - float
+     - Molar fraction of Hydrogen. Defaults to zero if undefined. If positive fraction, zmethod and cmethod are set to 'BNS'
    * - S
      - float
      - Skin. Defaults to zero if undefined
@@ -1208,10 +1251,16 @@ A ``gas_pvt`` object can be provided instead of individual gas composition param
      - Gas SG relative to air, Defaults to 0.75 if undefined
    * - gas_pvt
      - GasPVT
-     - GasPVT object. If provided, sg/co2/h2s/n2/h2/he/zmethod/cmethod/tc/pc are extracted from it
+     - GasPVT object. If provided, sg/co2/h2s/n2/h2/he/ag/zmethod/cmethod/tc/pc are extracted from it
    * - metric
      - bool
      - If True, inputs/outputs use Eclipse METRIC units. Defaults to False
+   * - he
+     - float
+     - Molar fraction of Helium. Defaults to 0. Keyword, last in the signature (new in 3.8.3). Like h2, a positive fraction forces zmethod and cmethod to 'BNS'; see *Helium in BNS*
+   * - ag
+     - bool
+     - BNS only. If True, the hydrocarbon pseudo-component Tc and Pc come from the associated-gas correlation instead of the default gas-condensate one; see *Associated gas in BNS*. Defaults to False. Keyword, last in the signature (new in 3.8.4). User-supplied tc/pc take precedence
 
 .. list-table:: Returns
    :widths: 10 15 40
@@ -1358,15 +1407,24 @@ A ``gas_pvt`` object can be provided instead of individual gas composition param
    * - h2s
      - float
      - Molar fraction of H2S. Defaults to zero if undefined
+   * - h2
+     - float
+     - Molar fraction of Hydrogen. Defaults to zero if undefined. If positive fraction, zmethod and cmethod are set to 'BNS'
    * - sg
      - float
      - Gas SG relative to air, Defaults to 0.75 if undefined
    * - gas_pvt
      - GasPVT
-     - GasPVT object. If provided, sg/co2/h2s/n2/h2/he/zmethod/cmethod/tc/pc are extracted from it
+     - GasPVT object. If provided, sg/co2/h2s/n2/h2/he/ag/zmethod/cmethod/tc/pc are extracted from it
    * - metric
      - bool
      - If True, inputs/outputs use Eclipse METRIC units. Defaults to False
+   * - he
+     - float
+     - Molar fraction of Helium. Defaults to 0. Keyword, last in the signature (new in 3.8.3). Like h2, a positive fraction forces zmethod and cmethod to 'BNS'; see *Helium in BNS*
+   * - ag
+     - bool
+     - BNS only. If True, the hydrocarbon pseudo-component Tc and Pc come from the associated-gas correlation instead of the default gas-condensate one; see *Associated gas in BNS*. Defaults to False. Keyword, last in the signature (new in 3.8.4). User-supplied tc/pc take precedence
 
 .. list-table:: Returns
    :widths: 10 15 40
@@ -1934,6 +1992,9 @@ Stores gas composition and method choices. Pre-computes critical temperature and
    * - he
      - float
      - Molar fraction of Helium. Defaults to 0. Keyword, last in the signature (new in 3.8.3). Like h2, a positive fraction forces zmethod and cmethod to 'BNS'; see *Helium in BNS*
+   * - ag
+     - bool
+     - BNS only. If True, the hydrocarbon pseudo-component Tc and Pc come from the associated-gas correlation instead of the default gas-condensate one; see *Associated gas in BNS*. Defaults to False. Keyword, last in the signature (new in 3.8.4). User-supplied tc/pc take precedence
    * - zmethod
      - string or z_method
      - Method for Z-factor calculation. Defaults to 'DAK'

{pyrestoolbox-3.8.3 → pyrestoolbox-3.8.5}/pyrestoolbox/docs/index.rst

@@ -46,7 +46,7 @@ Example notebooks
 ===========================  ====================================================
 File                         Content
 ===========================  ====================================================
-examples.ipynb               Worked examples across the modules plus BNS/BUR demonstrations
+examples.ipynb               Worked examples across the modules plus BNS demonstrations
 nodal_examples.ipynb         Multi-segment nodal framework examples
 nodal_hydrate_demo.ipynb     VLP, VFPPROD, nodal solutions and hydrate analysis
 ===========================  ====================================================

{pyrestoolbox-3.8.3 → pyrestoolbox-3.8.5}/pyrestoolbox/docs/nodal.rst

@@ -426,7 +426,7 @@ Returns flowing bottom hole pressure (psia, or barsa if metric=True) using the s
      - 'gas' or 'oil'
    * - gas_pvt
      - GasPVT
-     - Gas PVT object. If provided, extracts gas composition (sg, co2, h2s, n2, h2, he) and method selections for IPR calculations
+     - Gas PVT object. If provided, the gas-well VLP march evaluates Z and gas viscosity with its methods and composition (as ``gas_pvt.z()`` and ``gas_pvt.viscosity()``: DAK with PMC by default, or HY or BNS as configured, impurities and H2/He included), and IPR calculations use the same. Without it the march uses Hall-Yarborough Z on Sutton pseudo-criticals of ``gsg`` with Lee-Gonzalez-Eakin viscosity
    * - oil_pvt
      - OilPVT
      - Oil PVT object. If provided for oil wells, extracts api, sgsp, pb, rsb

{pyrestoolbox-3.8.3 → pyrestoolbox-3.8.5}/pyrestoolbox/docs/nodal_examples.ipynb

@@ -12,7 +12,7 @@
     "- **2, 3, and 4 segment** completions\n",
     "- **Inflow (IPR)** and **outflow (VLP)** curves with operating point solutions\n",
     "- Multiple VLP methods: Hagedorn-Brown (HB), Beggs & Brill (BB), Woldesemayat-Ghajar (WG)\n",
-    "- BUR gas PVT method (tuned 5-component Peng-Robinson EOS)"
+    "- BNS gas PVT method (tuned 5-component Peng-Robinson EOS)"
    ]
   },
   {
@@ -102,7 +102,7 @@
     "- 8,000 ft of 2.441\" tubing\n",
     "- 2,000 ft of 4.892\" casing below the tubing shoe\n",
     "\n",
-    "Uses BUR gas PVT with 5% CO2."
+    "Uses BNS gas PVT with 5% CO2."
    ]
   },
   {
@@ -111,8 +111,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Define GasPVT with BUR method\n",
-    "gpvt_1 = gas.GasPVT(sg=0.70, co2=0.05, zmethod='BUR', cmethod='BUR')\n",
+    "# Define GasPVT with BNS method\n",
+    "gpvt_1 = gas.GasPVT(sg=0.70, co2=0.05, zmethod='BNS', cmethod='BNS')\n",
     "print(f'Gas Tc = {gpvt_1.tc:.1f} deg R, Pc = {gpvt_1.pc:.1f} psia')\n",
     "print(f'Z @ 3000 psia, 220F = {gpvt_1.z(3000, 220):.4f}')\n",
     "print(f'Viscosity @ 3000 psia, 220F = {gpvt_1.viscosity(3000, 220):.4f} cP')"
@@ -169,7 +169,7 @@
     "- 3,000 ft of 2.441\" tubing — building angle (30 deg deviation)\n",
     "- 4,000 ft of 4.892\" casing — high angle (60 deg deviation)\n",
     "\n",
-    "BB and WG are suitable for deviated wells. Uses BUR gas PVT."
+    "BB and WG are suitable for deviated wells. Uses BNS gas PVT."
    ]
   },
   {
@@ -226,7 +226,7 @@
     "- 3,000 ft of 2.441\" tubing — tangent section (55 deg)\n",
     "- 4,000 ft of 4.892\" casing — near-horizontal (80 deg)\n",
     "\n",
-    "Uses WG method (well-suited for all inclinations) and BUR gas PVT."
+    "Uses WG method (well-suited for all inclinations) and BNS gas PVT."
    ]
   },
   {
@@ -548,9 +548,9 @@
    "metadata": {},
    "source": [
     "---\n",
-    "## Example 9: Gas Well with H2 Blend — BUR Method Auto-Selection\n",
+    "## Example 9: Gas Well with H2 Blend — BNS Method Auto-Selection\n",
     "\n",
-    "When hydrogen is present, GasPVT automatically selects BUR/BNS for both z-factor and critical property methods. \n",
+    "When hydrogen is present, GasPVT automatically selects BNS for both z-factor and critical property methods. \n",
     "3-segment well with 10% H2 in the gas."
    ]
   },
@@ -560,7 +560,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# GasPVT with H2 — auto-selects BNS/BUR\n",
+    "# GasPVT with H2 — auto-selects BNS\n",
     "gpvt_h2 = gas.GasPVT(sg=0.55, co2=0.02, h2=0.10)\n",
     "print(f'Z-method: {gpvt_h2.zmethod}')\n",
     "print(f'C-method: {gpvt_h2.cmethod}')\n",
@@ -592,7 +592,7 @@
     "print(f\"Operating BHP:  {result_h2['bhp']:.0f} psia\")\n",
     "\n",
     "plot_nodal(result_h2, well_type='gas',\n",
-    "           title='Example 9: Gas + 10% H2 Well — 3 Segments (BUR Auto-Selected)');"
+    "           title='Example 9: Gas + 10% H2 Well — 3 Segments (BNS Auto-Selected)');"
    ]
   },
   {
@@ -792,7 +792,7 @@
     "\n",
     "| Example | Well Type | Segments | Trajectory | VLP Method | Key Feature |\n",
     "|---------|-----------|----------|------------|------------|-------------|\n",
-    "| 1 | Gas | 2 | Vertical | BB | Basic multi-segment, BUR PVT |\n",
+    "| 1 | Gas | 2 | Vertical | BB | Basic multi-segment, BNS PVT |\n",
     "| 2 | Gas | 3 | Deviated | BB | Build + high-angle sections |\n",
     "| 3 | Gas | 4 | Near-horizontal | WG | 4-segment trajectory, WG method |\n",
     "| 4 | Gas | 1 vs 3 | Vertical vs Deviated | BB | VLP comparison overlay |\n",
@@ -800,7 +800,7 @@
     "| 6 | Oil | 3 | Deviated | BB | Deviated oil with OilPVT |\n",
     "| 7 | Oil | 4 | Near-horizontal | BB | 4-segment horizontal oil |\n",
     "| 8 | Gas | 3 | Deviated | HB/BB/WG/GRAY | Method comparison |\n",
-    "| 9 | Gas+H2 | 3 | Deviated | BB | H2 blend, BUR auto-selection |\n",
+    "| 9 | Gas+H2 | 3 | Deviated | BB | H2 blend, BNS auto-selection |\n",
     "| 10 | Gas | 4 | Deviated | WG | THP sensitivity |\n",
     "| 11 | Oil | 2 vs 4 | Vertical vs Deviated | BB | Side-by-side nodal comparison |\n",
     "| 12 | Gas | 2/3/4 | Progressive deviation | BB | fbhp table comparison |"