pyrestoolbox 3.2.0__tar.gz → 3.3.0__tar.gz

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

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

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

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "pyrestoolbox"
-version = "3.2.0"
+version = "3.3.0"
 description = "pyResToolbox - A collection of Reservoir Engineering Utilities"
 license = {text = "GPL-3.0-or-later"}
 authors = [{name = "Mark W. Burgoyne", email = "mark.w.burgoyne@gmail.com"}]

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

@@ -315,7 +315,7 @@ def brine_props(p: float = None, degf: float = None, wt: float = None, ch4_sat:
         / ((Mpa - vap_pressure) - 2 * dlambdadptm * m)
     )  # Eq 4.33
 
-    zee = gas.gas_z(p=p, sg=_SG_METHANE, degf=degf, zmethod='BNS',
+    zee = gas.gas_z(p=p, sg=_SG_METHANE, degf=degf, zmethod='BNS', cmethod='BNS',
                     co2=0, h2s=0, n2=0, h2=0)  # Z-Factor of pure methane
 
     vmch4g = zee * _R_CM3_MPA * degk / Mpa  # Eq 4.34
@@ -342,7 +342,7 @@ def brine_props(p: float = None, degf: float = None, wt: float = None, ch4_sat:
 
 
 
-    zee_sc = gas.gas_z(p=psc, sg=_SG_METHANE, degf=tsc, zmethod='BNS',
+    zee_sc = gas.gas_z(p=psc, sg=_SG_METHANE, degf=tsc, zmethod='BNS', cmethod='BNS',
                        co2=0, h2s=0, n2=0, h2=0)
     vmch4g_sc = zee_sc * _R_CM3_MPA * (273 + 15) / 0.1013  # Eq 4.34
     rsw_new = mch4 * vmch4g_sc / ((1000 + m * 58.4428) * vb0_sc)
@@ -1552,7 +1552,7 @@ class SoreideWhitson:
                 self.gas_comp.get(g, 0) * _SW_GAS_MW.get(g, 28.97)
                 for g in self.gas_comp
             ) / MW_AIR
-            zee = gas.gas_z(p=self.psia, sg=gas_sg, degf=self.degF, zmethod='BNS',
+            zee = gas.gas_z(p=self.psia, sg=gas_sg, degf=self.degF, zmethod='BNS', cmethod='BNS',
                             co2=self.gas_comp.get('CO2', 0),
                             h2s=self.gas_comp.get('H2S', 0),
                             n2=self.gas_comp.get('N2', 0),

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

@@ -1,3 +1,18 @@
+Changelist in 3.3.0:
+
+- **BNS Z-factor / critical-property coupling**: When either ``zmethod`` or ``cmethod`` is ``BNS``, both are now forced to ``BNS`` for thermodynamic consistency with a ``UserWarning`` naming the overruled counterpart. ``h2 > 0`` continues to auto-select BNS silently. Non-BNS methods (e.g. ``DAK`` + ``SUT``) remain freely mixable. Implemented via a single ``_resolve_methods`` helper applied at all gas public entry points plus ``GasPVT.__init__``.
+
+- **User-supplied ``tc`` / ``pc`` honored across every method** (including BNS). Semantics:
+
+  - ``SUT`` / ``PMC``: supplied values replace the *mixture* pseudo-critical Tc/Pc.
+  - ``BNS``: supplied values replace only the *inert-free hydrocarbon* pseudo-component Tc/Pc. Inert Tc/Pc (CO2, H2S, N2, H2) remain at BNS internal constants, and the BNS 5-component PR-EOS mixes them with the user-supplied HC Tc/Pc.
+
+  This is reflected in ``gas_tc_pc``, ``gas_z``, ``gas_ug``, ``gas_cg``, ``gas_bg``, ``gas_den``, ``gas_dmp``, ``gas_ponz2p``, ``gas_grad2sg``, and ``GasPVT`` (new ``tc=0, pc=0`` kwargs on the class constructor).
+
+- **Rust parity for user Tc/Pc**: The Rust batch paths (``dak_zfactor_batch``, ``hy_zfactor_batch``, ``bns_zfactor_batch``, ``gas_ug_lbc``/``gas_ug_lbc_batch``, ``gas_dmp_rust``, ``gas_ponz2p_rust``) now accept optional ``tc_user`` / ``pc_user`` parameters and apply the same override semantics as Python. Removes the previous Python fallback for BNS+user-Tc/Pc; Rust path is now always exercised.
+
+- 716 validation tests (up from 701 in 3.2.0). New coverage for BNS coupling warnings, ``GasPVT`` user Tc/Pc, and Rust-vs-Python parity for user Tc/Pc.
+
 Changelist in 3.2.0:
 
 - **DCA bug fixes**:

{pyrestoolbox-3.2.0 → pyrestoolbox-3.3.0}/pyrestoolbox/docs/gas.rst

@@ -64,6 +64,16 @@ Calculating gas Z-Factor of pure methane using DAK and PMC for critical properti
    **BNS method strongly recommended for high-inert or hydrogen-bearing gases.**
    When modelling gases with significant CO2 (>10%), H2S, N2, or any H2 content, the ``'BNS'`` Z-factor and critical property methods (tuned 5-component Peng-Robinson EOS) should be used. Standard correlations (DAK/HY/WYW with PMC/SUT) were developed for sweet natural gas and become unreliable at high impurity concentrations. The BNS method handles the full range from pure hydrocarbon to 100% inerts. When ``h2 > 0``, BNS is auto-selected. For pure or high-concentration CO2/H2S/N2 gases, explicitly set ``zmethod='BNS', cmethod='BNS'``.
 
+.. note::
+
+   **BNS coupling and user-supplied Tc/Pc.**
+   ``zmethod`` and ``cmethod`` are coupled for the BNS framework: if either is BNS, both are forced to BNS (a ``UserWarning`` is emitted if this overrules a user-chosen non-BNS method). Non-BNS methods are not coupled.
+
+   User-supplied ``tc`` and ``pc`` are always respected, but their meaning depends on the critical-property method:
+
+   - **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 5-component EOS; inert Tc/Pc (CO2, H2S, N2, H2) remain the BNS internal per-component constants.
+
 Calculating gas Z-Factor of pure CO2
 
 .. code-block:: python
@@ -139,7 +149,11 @@ pyrestoolbox.gas.gas_tc_pc
 
     gas_tc_pc(sg, co2 = 0, h2s = 0, n2 = 0, h2 = 0, cmethod = 'PMC', tc = 0, pc = 0, metric = False) -> tuple
 
-Returns a tuple of critical temperature (deg R, or K if metric=True) and critical pressure (psia, or barsa if metric=True) for hydrocarbon gas. If one or both of the tc and pc parameters are set to be non-zero, then this function will return that unchanged value for the corresponding critical parameter.
+Returns a tuple of critical temperature (deg R, or K if metric=True) and critical pressure (psia, or barsa if metric=True). If one or both of the ``tc`` and ``pc`` parameters are set to be non-zero, then this function will return that unchanged value for the corresponding critical parameter.
+
+For ``cmethod='SUT'`` and ``cmethod='PMC'``, the returned values describe *mixture* pseudo-critical properties (full gas, inerts included).
+
+For ``cmethod='BNS'``, the returned values describe the *inert-free hydrocarbon* pseudo-critical properties only. The supplied inert fractions (``co2``, ``h2s``, ``n2``, ``h2``) are used solely to back out the inert-free hydrocarbon specific gravity from the overall mixture SG; the BNS pseudo-critical correlation is then applied to that hydrocarbon SG. Inert species (CO2, H2S, N2, H2) carry their own per-component Tc/Pc internally within the BNS 5-component PR-EOS, and are *not* included in the value returned here.
 
 .. list-table:: Inputs
    :widths: 10 15 40
@@ -168,10 +182,10 @@ Returns a tuple of critical temperature (deg R, or K if metric=True) and critica
      - Method for calculating gas critical parameters. `Calculation Methods and Class Objects`_.
    * - tc
      - float
-     - Critical gas temperature (deg R, or K if metric=True). Uses cmethod correlation if not specified
+     - 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)
    * - pc
      - float
-     - Critical gas pressure (psia, or barsa if metric=True). Uses cmethod correlation if not specified
+     - Critical gas pressure (psia, or barsa if metric=True). Uses cmethod correlation if not specified. For BNS, overrides only the hydrocarbon pseudo-component Pc (inert Pc stay at BNS internal constants)
    * - metric
      - bool
      - If True, inputs/outputs use Eclipse METRIC units. Defaults to False
@@ -254,10 +268,10 @@ A float or list / array can be used for p, returning corresponding 1-D array of
      - Molar fraction of Hydrogen. Defaults to zero if undefined. zmethod and cmethod get overriden to 'BUR' if positive fraction.
    * - tc
      - float
-     - Critical gas temperature (deg R, or K if metric=True). Uses cmethod correlation if not specified
+     - 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)
    * - pc
      - float
-     - Critical gas pressure (psia, or barsa if metric=True). Uses cmethod correlation if not specified
+     - Critical gas pressure (psia, or barsa if metric=True). Uses cmethod correlation if not specified. For BNS, overrides only the hydrocarbon pseudo-component Pc (inert Pc stay at BNS internal constants)
    * - metric
      - bool
      - If True, inputs/outputs use Eclipse METRIC units. Defaults to False
@@ -334,10 +348,10 @@ Furnishing a positive value for zee means it will be used instead of calculating
      - Molar fraction of Hydrogen. Defaults to zero if undefined. Overrides methods to 'BUR' if positive fraction.
    * - tc
      - float
-     - Critical gas temperature (deg R, or K if metric=True). Uses cmethod correlation if not specified
+     - 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)
    * - pc
      - float
-     - Critical gas pressure (psia, or barsa if metric=True). Uses cmethod correlation if not specified
+     - Critical gas pressure (psia, or barsa if metric=True). Uses cmethod correlation if not specified. For BNS, overrides only the hydrocarbon pseudo-component Pc (inert Pc stay at BNS internal constants)
    * - zee
      - float, list or np.array
      - Z-Factor value, or list of values of same length as P, in case recalculation of Z-Factors is not needed. If undefined, will trigger Z-Factor calculation.
@@ -414,10 +428,10 @@ A float or list / array can be used for p, returning corresponding 1-D array of
      - Molar fraction of Hydrogen. Defaults to zero if undefined. If positive fraction, cmethod will override to 'BUR'
    * - tc
      - float
-     - Critical gas temperature (deg R, or K if metric=True). Uses cmethod correlation if not specified
+     - 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)
    * - pc
      - float
-     - Critical gas pressure (psia, or barsa if metric=True). Uses cmethod correlation if not specified
+     - Critical gas pressure (psia, or barsa if metric=True). Uses cmethod correlation if not specified. For BNS, overrides only the hydrocarbon pseudo-component Pc (inert Pc stay at BNS internal constants)
    * - metric
      - bool
      - If True, inputs/outputs use Eclipse METRIC units. Defaults to False
@@ -491,10 +505,10 @@ A float or list / array can be used for p, returning corresponding 1-D array of
      - Molar fraction of Hydrogen. Defaults to zero if undefined. If positive fraction, cmethod will override to 'BUR'
    * - tc
      - float
-     - Critical gas temperature (deg R, or K if metric=True). Uses cmethod correlation if not specified
+     - 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)
    * - pc
      - float
-     - Critical gas pressure (psia, or barsa if metric=True). Uses cmethod correlation if not specified
+     - Critical gas pressure (psia, or barsa if metric=True). Uses cmethod correlation if not specified. For BNS, overrides only the hydrocarbon pseudo-component Pc (inert Pc stay at BNS internal constants)
    * - metric
      - bool
      - If True, inputs/outputs use Eclipse METRIC units. Defaults to False
@@ -567,10 +581,10 @@ A float or list / array can be used for p, returning corresponding 1-D array of
      - Molar fraction of Hydrogen. Defaults to zero if undefined. If positive fraction, cmethod will override to 'BUR'
    * - tc
      - float
-     - Critical gas temperature (deg R, or K if metric=True). Uses cmethod correlation if not specified
+     - 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)
    * - pc
      - float
-     - Critical gas pressure (psia, or barsa if metric=True). Uses cmethod correlation if not specified
+     - Critical gas pressure (psia, or barsa if metric=True). Uses cmethod correlation if not specified. For BNS, overrides only the hydrocarbon pseudo-component Pc (inert Pc stay at BNS internal constants)
    * - metric
      - bool
      - If True, inputs/outputs use Eclipse METRIC units. Defaults to False
@@ -691,10 +705,10 @@ A float or list / array can be used for poverz, returning corresponding 1-D arra
      - Molar fraction of Hydrogen. Defaults to zero if undefined. If positive fraction, cmethod will override to 'BUR'
    * - tc
      - float
-     - Critical gas temperature (deg R, or K if metric=True). Uses cmethod correlation if not specified
+     - 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)
    * - pc
      - float
-     - Critical gas pressure (psia, or barsa if metric=True). Uses cmethod correlation if not specified
+     - Critical gas pressure (psia, or barsa if metric=True). Uses cmethod correlation if not specified. For BNS, overrides only the hydrocarbon pseudo-component Pc (inert Pc stay at BNS internal constants)
    * - rtol
      - float
      - relative solution tolerance as compared with abs([User P/Z - Calculated P/Z] / [User P/Z])
@@ -730,7 +744,7 @@ pyrestoolbox.gas.gas_grad2sg
 
     gas_grad2sg( grad, p, degf, zmethod='DAK', cmethod='PMC', co2 = 0, h2s = 0, n2 = 0, h2 = 0, tc = 0, pc = 0, rtol = 1E-7, metric = False) -> float
 
-Returns gas specific gravity consistent with observed gas gradient. Calculated through iterative solution method. Will fail if gas SG is below 0.55, or greater than 1.75
+Returns gas specific gravity consistent with observed gas gradient. Calculated through iterative solution method. Bisection bounds span pure H2 (SG ~0.070) to 3.0 to accommodate H2-blend and CO2-rich compositions; solutions outside this range will fail.
 
 .. list-table:: Inputs
    :widths: 10 15 40
@@ -768,10 +782,10 @@ Returns gas specific gravity consistent with observed gas gradient. Calculated t
      - Molar fraction of Hydrogen. Defaults to zero if undefined. If positive fraction, cmethod will override to 'BUR'
    * - tc
      - float
-     - Critical gas temperature (deg R, or K if metric=True). Uses cmethod correlation if not specified
+     - 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)
    * - pc
      - float
-     - Critical gas pressure (psia, or barsa if metric=True). Uses cmethod correlation if not specified
+     - Critical gas pressure (psia, or barsa if metric=True). Uses cmethod correlation if not specified. For BNS, overrides only the hydrocarbon pseudo-component Pc (inert Pc stay at BNS internal constants)
    * - rtol
      - float
      - relative solution tolerance as compared with abs([User grad - Calculated grad] / [User grad])
@@ -847,10 +861,10 @@ Integrates the equation: m(p) = 2 * p / (ug * z)
      - Molar fraction of Hydrogen. Defaults to zero if undefined. If positive fraction, cmethod will override to 'BUR'
    * - tc
      - float
-     - Critical gas temperature (deg R, or K if metric=True). Uses cmethod correlation if not specified
+     - 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)
    * - pc
      - float
-     - Critical gas pressure (psia, or barsa if metric=True). Uses cmethod correlation if not specified
+     - Critical gas pressure (psia, or barsa if metric=True). Uses cmethod correlation if not specified. For BNS, overrides only the hydrocarbon pseudo-component Pc (inert Pc stay at BNS internal constants)
    * - metric
      - bool
      - If True, inputs/outputs use Eclipse METRIC units. Defaults to False
@@ -973,10 +987,10 @@ A ``gas_pvt`` object can be provided instead of individual gas composition param
      - Method for calculating gas critical parameters. `Calculation Methods and Class Objects`_.
    * - tc
      - float
-     - Critical gas temperature (deg R, or K if metric=True). Uses cmethod correlation if not specified
+     - 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)
    * - pc
      - float
-     - Critical gas pressure (psia, or barsa if metric=True). Uses cmethod correlation if not specified
+     - Critical gas pressure (psia, or barsa if metric=True). Uses cmethod correlation if not specified. For BNS, overrides only the hydrocarbon pseudo-component Pc (inert Pc stay at BNS internal constants)
    * - n2
      - float
      - Molar fraction of Nitrogen. Defaults to zero if undefined
@@ -1131,10 +1145,10 @@ A ``gas_pvt`` object can be provided instead of individual gas composition param
      - Method for calculating gas critical parameters. `Calculation Methods and Class Objects`_.
    * - tc
      - float
-     - Critical gas temperature (deg R, or K if metric=True). Uses cmethod correlation if not specified
+     - 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)
    * - pc
      - float
-     - Critical gas pressure (psia, or barsa if metric=True). Uses cmethod correlation if not specified
+     - Critical gas pressure (psia, or barsa if metric=True). Uses cmethod correlation if not specified. For BNS, overrides only the hydrocarbon pseudo-component Pc (inert Pc stay at BNS internal constants)
    * - n2
      - float
      - Molar fraction of Nitrogen. Defaults to zero if undefined