pyrestoolbox 3.4.0__tar.gz → 3.5.0__tar.gz

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

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

{pyrestoolbox-3.4.0 → pyrestoolbox-3.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "pyrestoolbox"
-version = "3.4.0"
+version = "3.5.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.4.0 → pyrestoolbox-3.5.0}/pyrestoolbox/brine/_lib_vle_engine.py

@@ -2106,15 +2106,21 @@ class SWMultiComponentFlash:
         # specialised ks models (Dubessy CO2, Akinfiev H2S, Li HC,
         # Mao-Duan N2, Duan-Sun CO2) are applied in self.calc_gamma()
         # on the Python side.
-        if _RUST_AVAILABLE:
+        #
+        # Restricted to framework='proposed': the Rust flash hardcodes the
+        # MC-3 water alpha and the proposed-framework kij_AQ. The 'dropin'
+        # and 'sw_original' frameworks use a salinity-dependent Soreide water
+        # alpha and different kij_AQ correlations that Rust does not implement,
+        # so they must take the Python path to avoid a silent downgrade.
+        if _RUST_AVAILABLE and self.framework == 'proposed':
             try:
                 gamma_arr = np.asarray(gamma, dtype=float) if gamma is not None \
                     else np.ones(self.nc)
-                V, x_r, y_r = _rust.flash_tp_rust(
+                V, x_r, y_r, conv_r = _rust.flash_tp_rust(
                     T_K, P_Pa, z.tolist(), list(self.names),
                     0.0, mode, gamma_arr.tolist(),
                 )
-                return V, np.array(x_r), np.array(y_r), True
+                return V, np.array(x_r), np.array(y_r), conv_r
             except (ImportError, AttributeError):
                 pass
 
@@ -2269,8 +2275,12 @@ class SWMultiComponentFlash:
             salinity_method = 'explicit'
 
         # Rust acceleration path: compute gamma in Python (correct ks models),
-        # then use Rust flash_tp for the two flashes.
-        if _RUST_AVAILABLE and salinity_method == 'gamma_phi':
+        # then use Rust flash_tp for the two flashes. Restricted to
+        # framework='proposed' — Rust only implements the proposed-framework
+        # water alpha (MC-3) and kij_AQ; 'dropin'/'sw_original' would be
+        # silently downgraded to 'proposed', so they take the Python path.
+        if (_RUST_AVAILABLE and salinity_method == 'gamma_phi'
+                and self.framework == 'proposed'):
             try:
                 gamma_aq = None
                 if self.salinity > 0:
@@ -2281,11 +2291,11 @@ class SWMultiComponentFlash:
                     else [1.0] * self.nc
                 names_list = list(self.names)
 
-                V_aq, x_aq_r, y_aq_r = _rust.flash_tp_rust(
+                V_aq, x_aq_r, y_aq_r, conv_aq = _rust.flash_tp_rust(
                     T_K, P_Pa, z.tolist(), names_list,
                     self.salinity, 'AQ', gamma_list,
                 )
-                V_na, x_na_r, y_na_r = _rust.flash_tp_rust(
+                V_na, x_na_r, y_na_r, conv_na = _rust.flash_tp_rust(
                     T_K, P_Pa, z.tolist(), names_list,
                     self.salinity, 'NA', [1.0] * self.nc,
                 )
@@ -2296,7 +2306,7 @@ class SWMultiComponentFlash:
                 result = {
                     'x_aq': x_aq, 'y_na': y_na, 'K_true': K_true,
                     'V_aq': V_aq, 'V_na': V_na,
-                    'converged_aq': True, 'converged_na': True,
+                    'converged_aq': conv_aq, 'converged_na': conv_na,
                     'component_names': self.names,
                     'salinity_method': salinity_method,
                     'vlle_warning': False,

{pyrestoolbox-3.4.0 → pyrestoolbox-3.5.0}/pyrestoolbox/brine/brine.py

@@ -967,9 +967,10 @@ class CO2_Brine_Mixture():
         """
         if _RUST_AVAILABLE:
             try:
-                xco2, yco2, yh2o, rhogas, gasz = _rust.co2_brine_solubility_rust(
+                xco2, yco2, yh2o, rhogas, gasz, conv = _rust.co2_brine_solubility_rust(
                     self.pBar, self.degC, self.ppm
                 )
+                self.converged = conv
                 self.x = np.array([xco2, 1.0 - xco2 - (self.xSalt if self.xSalt else 0.0)])
                 self.y = np.array([yco2, yh2o])
                 self.rhoGas = rhogas
@@ -1939,8 +1940,10 @@ class SoreideWhitson:
                 gas_ply = _VLE_TO_PLYASUNOV.get(gas_vle, gas_vle.upper())
                 vphi_eff_p1 += yi * _plyasunov_V_phi(gas_ply, tKel, Mpa_p1)
 
-            numerator_p1 = 1.0 + self.x_total * mw_eff / (MWWAT * x1)
-            denom_p1 = self.x_total * vphi_eff_p1 / (MWWAT * x1) + 1.0 / rho_brine_p1_gcc
+            # Garcia Eq. 18 at P+1, same algebraically reformulated (non-singular)
+            # form as Step 3 — multiply top/bot through by M1*x1.
+            numerator_p1 = MWWAT * x1 + self.x_total * mw_eff
+            denom_p1 = self.x_total * vphi_eff_p1 + MWWAT * x1 / rho_brine_p1_gcc
             rho_p1_gcc = numerator_p1 / denom_p1
         else:
             rho_p1_gcc = rho_brine_p1_gcc

{pyrestoolbox-3.4.0 → pyrestoolbox-3.5.0}/pyrestoolbox/docs/changelist.rst

@@ -1,3 +1,42 @@
+Changelist in 3.5.0:
+
+- **Gas non-Darcy & partial-penetration pseudoskins** — three new public functions in ``pyrestoolbox.gas`` plus two matching ``GasPVT`` convenience methods. Oilfield + metric unit support throughout.
+
+  - ``gas.gas_hvf_beta(k, method='FK' | 'JONES' | 'TCK', phi=0, metric=False)`` — Forchheimer high-velocity-flow coefficient β. Three correlations: ``'FK'`` (default, log-log fit of Firoozabadi & Katz 1979 JPT Feb, consolidated-rock β(k) chart), ``'JONES'`` (Jones 1987 SPE-16949), ``'TCK'`` (Tek, Coats, Katz 1962 JPT Jul, requires ``phi``). Returns β in 1/ft (or 1/m if ``metric=True``).
+  - ``gas.gas_non_darcy_skin(qg, k, h_perf, rw, mug, sg, krg=1.0, beta_method='FK', phi=0, metric=False)`` — returns ``{'beta', 'D', 'S_hvf'}`` where D uses the standard ``2.222e-15 · β · γg · k / (μg · h · rw)`` form (Jones 1987; Odeh, Moreland & Schueler 1975 JPT Dec). Output ``D`` is in day/MSCF (or day/sm3 if metric) and can be passed directly to ``gas_rate_radial(D=...)``. ``krg < 1`` evaluates β at the damaged-zone permeability ``k' = k·krg`` for a pessimistic S\ :sub:`hvf`.
+  - ``gas.gas_partial_penetration_skin(htot, htop, hbot, rw, kh_kv=10)`` — partial-penetration pseudoskin by direct evaluation of the Streltsova-Adams (1979) SPE-7486 analytical series. Bessel K\ :sub:`0` from ``scipy.special.k0``; vectorised summation to 20,000 terms (sub-millisecond). Warns when the series tail suggests incomplete convergence for very thin wellbores. Unit-agnostic — only ratios enter the formula, so inputs share any consistent length unit.
+  - ``GasPVT.non_darcy_skin(qg, p, degf, k, h_perf, rw, krg=1, beta_method='FK', phi=0)`` and ``GasPVT.partial_penetration_skin(htot, htop, hbot, rw, kh_kv=10)`` — the former auto-computes μ\ :sub:`g` from stored PVT state; both honour the ``GasPVT.metric`` flag.
+
+  18 new unit tests in ``test_gas.py`` (all three β correlations, metric round-trip, damaged-zone, series convergence, geometry validation, ``GasPVT`` delegation). 12 new doc-example tests in ``test_doc_examples.py`` pin every RST example value. Reference S\ :sub:`p` values verified against a 50,000-term direct evaluation of the Streltsova-Adams series.
+
+- **PVTO export format fix** (``simtools.make_bot_og(pvto=True, export=True)``). The exported ``PVTO.INC`` placed Eclipse's ``/`` stem-terminator on every saturated row, prematurely closing each stem before its undersaturated continuation rows. A strict parser would then read each continuation row as an unset stem and either error or drop the data. The saturated row now omits ``/`` when undersaturated rows follow; the terminator moves to the LAST undersaturated row of the stem, matching the reference example in the Eclipse manual (``PVTO`` keyword). Stems with no undersaturated extension still carry ``/`` on the saturated row, and the final null-record ``/`` on its own line still terminates the table. Underlying ``usat`` data returned in the results dict was already correct — only the export layout changed.
+
+- **Removed dead module** ``pyrestoolbox/oil/oil.py``. Pre-April-2026 monolith superseded by the ``_correlations.py`` / ``_density.py`` / ``_tables.py`` / etc. sub-modules. Nothing in the package or tests imported from it. No public-API change — ``from pyrestoolbox import oil`` and ``oil.<func>`` keep working via ``oil/__init__.py`` re-exports.
+
+- **Brine framework correctness (Rust path)**. ``SoreideWhitson(framework='dropin')`` and ``framework='sw_original'`` were silently computed as ``'proposed'`` whenever the Rust accelerator was installed: the Rust flash hardcodes the proposed-framework MC-3 water alpha and kij\ :sub:`AQ`, with no framework parameter. The Rust dispatch in ``brine._lib_vle_engine`` (``flash_tp`` and ``calc_equilibrium``) is now gated on ``framework == 'proposed'``; the other two frameworks take the framework-aware Python path. Pure-Python results were always correct. Adds a regression test exercising both non-proposed frameworks.
+
+- **Brine convergence flag (Rust path)**. ``flash_tp_rust`` and ``co2_brine_solubility_rust`` now return the convergence bool they compute, so ``SoreideWhitson``/``CO2_Brine_Mixture`` ``.converged`` (and the ``converged_aq``/``converged_na`` flash flags) report the real outcome instead of being hardcoded ``True`` when Rust is active.
+
+- **Oil ``oil_harmonize`` default ``pbmethod`` unified to VALMC** (was ``VELAR``), matching ``oil_pbub`` / ``oil_rs`` / ``oil_co`` / ``OilPVT``. Previously ``oil_harmonize`` and the other oil functions returned mutually inconsistent Pb/Rsb on identical inputs. The deprecated ``OilPVT.from_harmonize`` default was aligned too. **Behaviour change**: default ``oil_harmonize`` output shifts for callers that relied on the old default (e.g. the ``rsb_frac`` returned when both ``pb`` and ``rsb`` are supplied). Pass ``pbmethod='VELAR'`` explicitly to retain the old behaviour.
+
+- **Nodal HB VLP Rust/Python parity**. Hampson-Brill superficial-gas-velocity and gas-density constants in the Rust accelerator (``35.3741`` molar-volume factor, ``10.73`` vs ``10.732``, ``29.0`` vs ``28.97`` air MW) are aligned with the Python path, making all four VLP methods bit-exact between Rust and Python. The HB-oil/HB-gas parity tests are tightened from ``rtol=1e-3`` to ``1e-4``. Affected HB doc-example BHPs shifted by ~0.05–0.25% to the now-identical Rust/Python value (e.g. ``fbhp`` oil 1771.47 → 1770.58 psi); RST examples updated to match.
+
+- **``simtools.rr_solver`` single-phase guard**. Single-phase feeds (all-liquid or all-vapor) previously fell through to the two-phase Nielsen-Lia solver and returned ``inf``/``nan`` with only a divide-by-zero warning. They are now detected up front and return the trivial split (V=0 or V=1); non-positive K-values raise ``ValueError``.
+
+- **``nodal.fthp`` input validation**. ``fthp`` now validates ``well_type`` / ``vlpmethod`` / ``bhp`` at entry like the other public nodal functions, instead of only erroring transitively through the inner ``fbhp`` solve.
+
+- **``validate_pe_inputs`` array safety**. The ``sg`` and inert-fraction checks are now array-safe (previously ``sg <= 0`` raised an ambiguous-truth-value error on array inputs).
+
+- **Brine undersaturated-compressibility density** now uses the same algebraically reformulated, non-singular Garcia Eq. 18 as the saturated-density step (removes the ``xCO2 → 1`` singularity from the P+1 density used in ``Cf_usat``). Mathematically identical for ``xCO2 < 1``.
+
+- **Removed dead Rust exports** ``oil_bo_mccain_rust`` and ``calc_equilibrium_rust`` (and their now-orphaned internals), which had no Python callers. New Rust-vs-Python parity tests added for ``gas_ponz2p`` and ``simtools.influence_tables`` — the two live accelerated paths that previously had no parity coverage.
+
+- **``oil_matbal`` aquifer water influx**. New optional ``We`` parameter (cumulative aquifer influx in reservoir volume, rb | rm3) brings oil material balance to parity with ``gas_matbal``. The influx is subtracted from underground withdrawal before estimating OOIP (Havlena-Odeh ``F - We = N·[Eo + m·Eg + (1+m)·Efw]``) — feeding both the Python and Rust regression objectives — and a Water Drive Index (``'WDI'``) is added to ``drive_indices`` so the indices sum to 1 under water drive. Fully backward-compatible: with ``We`` omitted, ``WDI`` is all-zero and OOIP/DDI/SDI/CDI are unchanged.
+
+- **Internal: hydrate code split out of ``gas.py``**. ``gas_hydrate``, ``HydrateResult``, the HFT/HFP/Østergaard helpers and their constants now live in ``pyrestoolbox/gas/_hydrate.py`` (≈480 lines carved off the ``gas.py`` monolith). Public API is unchanged — ``gas.gas_hydrate`` and ``gas.HydrateResult`` are re-exported. ``_hydrate`` imports ``gas_water_content`` lazily, so there is no circular import.
+
+- 838 validation tests (up from 812 in 3.4.0).
+
 Changelist in 3.4.0:
 
 - **BREAKING — Brine metric default standardization**: ``CO2_Brine_Mixture`` and ``SoreideWhitson`` constructors now default to ``metric=False`` (oilfield units) to match ``brine_props`` and every other pyrestoolbox API. Previously they defaulted to ``metric=True``. Existing callers that relied on the old default must either pass ``metric=True`` explicitly or switch their input units to psia / degF. RST and notebook examples that relied on the default have been updated to pass ``metric=True`` explicitly.

{pyrestoolbox-3.4.0 → pyrestoolbox-3.5.0}/pyrestoolbox/docs/gas.rst

@@ -138,6 +138,12 @@ Function List
      - `pyrestoolbox.gas.gas_rate_linear`_
    * - Gas Hydrate Prediction
      - `pyrestoolbox.gas.gas_hydrate`_
+   * - Forchheimer HVF Coefficient (β)
+     - `pyrestoolbox.gas.gas_hvf_beta`_
+   * - Non-Darcy (HVF) Skin
+     - `pyrestoolbox.gas.gas_non_darcy_skin`_
+   * - Partial-Penetration Pseudoskin
+     - `pyrestoolbox.gas.gas_partial_penetration_skin`_
    * - Gas PVT Wrapper
      - `pyrestoolbox.gas.GasPVT`_
 
@@ -1414,6 +1420,228 @@ With reservoir P,T (gas equilibrated at reservoir, hydrate assessment at wellhea
     True
 
 
+pyrestoolbox.gas.gas_hvf_beta
+=============================
+
+.. code-block:: python
+
+    gas_hvf_beta(k, method='FK', phi=0.0, metric=False) -> float
+
+Returns the Forchheimer high-velocity-flow (inertial) coefficient β, used in non-Darcy flow calculations. Three correlations are available. All return β in 1/ft (or 1/m when ``metric=True``) for permeability ``k`` in md.
+
+.. list-table:: β correlations
+   :widths: 8 25 20
+   :header-rows: 1
+
+   * - method
+     - Correlation
+     - Source
+   * - ``'FK'``
+     - β = 2.172e10 · k⁻¹·²⁰¹
+     - Log-log fit of Firoozabadi & Katz (1979) JPT Feb, pp.211-216 (SPE-6827) consolidated-rock β(k) chart. Default.
+   * - ``'JONES'``
+     - β = 6.15e10 · k⁻¹·⁵⁵
+     - Jones, S.C. (1987) SPE-16949
+   * - ``'TCK'``
+     - β = 1.88e10 / (k¹·⁴⁷ · φ⁰·⁵³)
+     - Tek, Coats, Katz (1962) JPT Jul, pp.799-806. Requires ``phi``.
+
+.. list-table:: Inputs
+   :widths: 10 15 40
+   :header-rows: 1
+
+   * - Parameter
+     - Type
+     - Description
+   * - k
+     - float
+     - Permeability (md). To evaluate β at a damaged-zone permeability, pass ``k' = k * krg``.
+   * - method
+     - string
+     - ``'FK'`` (default), ``'JONES'``, or ``'TCK'``.
+   * - phi
+     - float
+     - Porosity fraction. Required for ``method='TCK'``.
+   * - metric
+     - bool
+     - If True, returns β in 1/m; else 1/ft. Defaults to False.
+
+Examples:
+
+.. code-block:: python
+
+    >>> gas.gas_hvf_beta(100.0)                           # FK, 100 md
+    86071589.04028143
+    >>> gas.gas_hvf_beta(100.0, method='JONES')
+    48851186.4355433
+    >>> gas.gas_hvf_beta(100.0, method='TCK', phi=0.25)
+    45003847.531218514
+    >>> gas.gas_hvf_beta(100.0, metric=True)              # 1/m
+    282387103.1505296
+
+
+pyrestoolbox.gas.gas_non_darcy_skin
+===================================
+
+.. code-block:: python
+
+    gas_non_darcy_skin(qg, k, h_perf, rw, mug, sg, krg=1.0,
+                       beta_method='FK', phi=0.0, metric=False) -> dict
+
+Returns the rate-dependent (high-velocity-flow) pseudoskin for a gas well. Computes β via ``gas_hvf_beta``, the non-Darcy coefficient D following Jones (1987) SPE-16949 / Odeh, Moreland, Schueler (1975) JPT Dec pp.1501-1504, and the skin S\ :sub:`hvf` = D · q\ :sub:`g`.
+
+Formula (field units):
+
+    D [day/MSCF] = 2.222×10⁻¹⁵ · β · γ\ :sub:`g` · k / (μ\ :sub:`g` · h\ :sub:`perf` · r\ :sub:`w`)
+
+where β is in 1/ft, k in md, μ\ :sub:`g` in cP, h\ :sub:`perf` and r\ :sub:`w` in ft.
+
+.. list-table:: Inputs
+   :widths: 10 15 40
+   :header-rows: 1
+
+   * - Parameter
+     - Type
+     - Description
+   * - qg
+     - float
+     - Gas rate (MSCF/D | sm3/D).
+   * - k
+     - float
+     - Absolute permeability (md).
+   * - h_perf
+     - float
+     - Perforated interval thickness (ft | m).
+   * - rw
+     - float
+     - Wellbore radius (ft | m).
+   * - mug
+     - float
+     - Gas viscosity at reservoir conditions (cP). Obtain from ``gas_ug`` or ``GasPVT.viscosity()``.
+   * - sg
+     - float
+     - Gas specific gravity relative to air.
+   * - krg
+     - float
+     - Gas relative permeability at critical oil saturation. If < 1.0, β is evaluated at the damaged-zone permeability ``k' = k * krg``, producing a more pessimistic S\ :sub:`hvf`. Defaults to 1.0 (undamaged).
+   * - beta_method
+     - string
+     - ``'FK'`` | ``'JONES'`` | ``'TCK'`` (see `pyrestoolbox.gas.gas_hvf_beta`_). Defaults to ``'FK'``.
+   * - phi
+     - float
+     - Porosity fraction. Required for ``beta_method='TCK'``.
+   * - metric
+     - bool
+     - If True, inputs in (sm3/D, m, m) and D returned in day/sm3; else (MSCF/D, ft, ft) and D in day/MSCF. Defaults to False.
+
+Returns a ``dict`` with keys:
+
+.. list-table:: Returns
+   :widths: 10 40
+   :header-rows: 1
+
+   * - Key
+     - Description
+   * - ``'beta'``
+     - Forchheimer coefficient (1/ft | 1/m)
+   * - ``'D'``
+     - Non-Darcy coefficient (day/MSCF | day/sm3). Suitable for passing directly to ``gas_rate_radial(D=...)``.
+   * - ``'S_hvf'``
+     - Rate-dependent skin (dimensionless).
+
+Example (field units):
+
+.. code-block:: python
+
+    >>> r = gas.gas_non_darcy_skin(qg=10000, k=100, h_perf=100, rw=0.33,
+    ...                             mug=0.025, sg=0.7)
+    >>> round(r['beta'], 0)
+    86071589.0
+    >>> round(r['D'] * 1e5, 4)   # D in units of 1e-5 day/MSCF
+    1.6227
+    >>> round(r['S_hvf'], 4)
+    0.1623
+
+Using damaged-zone β (krg < 1) and the TCK correlation:
+
+.. code-block:: python
+
+    >>> r = gas.gas_non_darcy_skin(qg=10000, k=100, h_perf=100, rw=0.33,
+    ...                             mug=0.025, sg=0.7, krg=0.7,
+    ...                             beta_method='TCK', phi=0.22)
+    >>> round(r['S_hvf'], 4)
+    0.1534
+
+Metric units (sm3/D, m) — same well, same skin:
+
+.. code-block:: python
+
+    >>> r = gas.gas_non_darcy_skin(qg=283168.5, k=100, h_perf=30.48, rw=0.1006,
+    ...                             mug=0.025, sg=0.7, metric=True)
+    >>> round(r['S_hvf'], 4)
+    0.1622
+
+
+pyrestoolbox.gas.gas_partial_penetration_skin
+=============================================
+
+.. code-block:: python
+
+    gas_partial_penetration_skin(htot, htop, hbot, rw, kh_kv=10.0) -> float
+
+Returns the partial-penetration pseudoskin S\ :sub:`p` for a vertical well in a radial anisotropic reservoir, using the analytical series solution of Streltsova-Adams, T.D. (1979) "Pressure Drawdown in a Well with Limited Flow Entry," SPE J. Nov 1979, pp.1469-1476 (SPE-7486).
+
+The series is summed directly (up to 20,000 terms, vectorised) with Bessel K₀ evaluated via ``scipy.special.k0``. A warning is emitted when the tail of the summation suggests the series has not fully converged (typical for very thin wellbores, i.e. r\ :sub:`w`/h\ :sub:`tot` ≪ 10⁻³ combined with small k\ :sub:`v`).
+
+**All length inputs must share a consistent unit** (ft or m — only ratios enter the formula), so there is no separate ``metric`` flag on this function.
+
+.. list-table:: Inputs
+   :widths: 10 15 40
+   :header-rows: 1
+
+   * - Parameter
+     - Type
+     - Description
+   * - htot
+     - float
+     - Total formation thickness (no-flow to no-flow).
+   * - htop
+     - float
+     - Distance from formation top to top of perforated interval.
+   * - hbot
+     - float
+     - Distance from formation top to bottom of perforated interval.
+   * - rw
+     - float
+     - Wellbore radius.
+   * - kh_kv
+     - float
+     - Horizontal-to-vertical permeability anisotropy ratio (k\ :sub:`h`/k\ :sub:`v`). Defaults to 10.0. Set to 0 to treat vertical permeability as negligible (returns S\ :sub:`p` = 0).
+
+Example (field units, ft):
+
+.. code-block:: python
+
+    >>> gas.gas_partial_penetration_skin(htot=164.04, htop=32.81, hbot=147.64,
+    ...                                   rw=0.3543, kh_kv=8.0)
+    2.155398050852645
+
+Metric call using meters — same well, dimensionless result is essentially identical:
+
+.. code-block:: python
+
+    >>> gas.gas_partial_penetration_skin(htot=50.0, htop=10.0, hbot=45.0,
+    ...                                   rw=0.108, kh_kv=8.0)
+    2.155481748242132
+
+Fully perforated interval (S\ :sub:`p` → 0):
+
+.. code-block:: python
+
+    >>> round(gas.gas_partial_penetration_skin(htot=100, htop=0, hbot=100, rw=0.33), 10)
+    0.0
+
+
 pyrestoolbox.gas.GasPVT
 ========================
 
@@ -1495,3 +1723,16 @@ Using metric units (pressure in barsa, temperature in deg C):
     >>> gpvt_m.density(137.9, 82.2)
     97.36871728783241
 
+``GasPVT`` also exposes two skin helpers that reuse stored PVT state for viscosity:
+
+.. code-block:: python
+
+    >>> gpvt = gas.GasPVT(sg=0.70)
+    >>> r = gpvt.non_darcy_skin(qg=10000, p=3000, degf=200,
+    ...                          k=100, h_perf=100, rw=0.33, krg=0.7)
+    >>> round(r['S_hvf'], 4)
+    0.3044
+    >>> round(gpvt.partial_penetration_skin(htot=50, htop=10, hbot=45,
+    ...                                      rw=0.108, kh_kv=8), 4)
+    2.1555
+

{pyrestoolbox-3.4.0 → pyrestoolbox-3.5.0}/pyrestoolbox/docs/matbal.rst

@@ -192,13 +192,13 @@ pyrestoolbox.matbal.oil_matbal
 .. code-block:: python
 
     oil_matbal(p, Np, degf, api=0, sg_sp=0, sg_g=0, pb=0, rsb=0,
-               Rp=None, Wp=None, Wi=None, Gi=None,
+               Rp=None, Wp=None, Wi=None, Gi=None, We=None,
                Bw=1.0, m=0, cf=0, sw_i=0, cw=0,
                rsmethod='VELAR', bomethod='MCAIN',
                zmethod='DAK', cmethod='PMC', metric=False,
                pvt_table=None, regress=None) -> OilMatbalResult
 
-Havlena-Odeh oil material balance for OOIP estimation. Computes underground withdrawal (F), oil expansion (Eo), gas cap expansion (Eg), and formation/water compressibility (Efw) terms at each pressure step. OOIP is estimated as the mean of F/(Eo + m*Eg + (1+m)*Efw) across valid steps. Drive indices (DDI, SDI, CDI) are computed at each step.
+Havlena-Odeh oil material balance for OOIP estimation. Computes underground withdrawal (F), oil expansion (Eo), gas cap expansion (Eg), and formation/water compressibility (Efw) terms at each pressure step. When cumulative aquifer influx ``We`` is supplied it is subtracted from the withdrawal first (``F - We = N·[Eo + m*Eg + (1+m)*Efw]``); OOIP is the mean of ``(F - We)/(Eo + m*Eg + (1+m)*Efw)`` across valid steps. Drive indices (DDI, SDI, CDI, WDI) are computed at each step.
 
 .. list-table:: Inputs
    :widths: 10 15 40
@@ -243,6 +243,9 @@ Havlena-Odeh oil material balance for OOIP estimation. Computes underground with
    * - Gi
      - array-like, optional
      - Cumulative gas injection (scf | sm3). Default all zeros
+   * - We
+     - array-like, optional
+     - Cumulative aquifer water influx in reservoir volume (rb | rm3). Subtracted from withdrawal before estimating OOIP and surfaced as the 'WDI' water-drive index. No metric conversion (already a reservoir volume). Default all zeros
    * - Bw
      - float
      - Water FVF (rb/stb | rm3/sm3, default 1.0)
@@ -304,7 +307,7 @@ Havlena-Odeh oil material balance for OOIP estimation. Computes underground with
      - Formation and water compressibility term at each step
    * - drive_indices
      - dict
-     - Drive index fractions at each step: 'DDI' (depletion), 'SDI' (segregation/gas cap), 'CDI' (compaction/water). Each maps to np.ndarray
+     - Drive index fractions at each step: 'DDI' (depletion), 'SDI' (segregation/gas cap), 'CDI' (compaction/expansion), 'WDI' (water/aquifer influx). Each maps to np.ndarray. 'WDI' is all-zero when no ``We`` is supplied
    * - p
      - np.ndarray
      - Pressure array used
@@ -330,6 +333,22 @@ Examples:
     >>> r.drive_indices['DDI'][1]
     0.7108509458427899
 
+Water-drive Example (aquifer influx ``We``):
+
+.. code-block:: python
+
+    >>> r = matbal.oil_matbal(
+    ...     p=[4000, 3500, 3000, 2500],
+    ...     Np=[0, 1e6, 3e6, 6e6],
+    ...     degf=220, api=35, sg_sp=0.75,
+    ...     pb=3500, rsb=500, cf=3e-6, sw_i=0.2, cw=3e-6,
+    ...     We=[0, 3e5, 1.2e6, 3.0e6]
+    ... )
+    >>> r.ooip
+    58621028.243056096
+    >>> r.drive_indices['WDI'][-1]
+    0.4055063920332815
+
 Regression Example (optimizing m and cf):
 
 .. code-block:: python

{pyrestoolbox-3.4.0 → pyrestoolbox-3.5.0}/pyrestoolbox/docs/nodal.rst

@@ -499,7 +499,7 @@ Gas well:
     >>> from pyrestoolbox import nodal
     >>> c = nodal.Completion(tid=2.441, length=10000, tht=100, bht=200)
     >>> nodal.fbhp(thp=500, completion=c, vlpmethod='HB', well_type='gas', qg_mmscfd=5.0, gsg=0.65, cgr=10, qw_bwpd=10, api=45, oil_vis=1.0)
-    952.6868477414688
+    954.8384864703888
 
 Oil well:
 
@@ -507,7 +507,7 @@ Oil well:
 
     >>> c = nodal.Completion(tid=2.441, length=8000, tht=100, bht=180)
     >>> nodal.fbhp(thp=200, completion=c, vlpmethod='HB', well_type='oil', qt_stbpd=2000, gor=800, wc=0.3, gsg=0.65, pb=2500, rsb=500, sgsp=0.65, api=35)
-    1771.4717888847196
+    1770.5840097037972
 
 Oil well using OilPVT object:
 
@@ -516,7 +516,7 @@ Oil well using OilPVT object:
     >>> from pyrestoolbox import oil
     >>> opvt = oil.OilPVT(api=35, sg_sp=0.65, pb=2500, rsb=500)
     >>> nodal.fbhp(thp=200, completion=c, vlpmethod='HB', well_type='oil', oil_pvt=opvt, qt_stbpd=2000, gor=800, wc=0.3, gsg=0.65)
-    1772.2397895054948
+    1771.3518436635964
 
 Deviated well using WellSegment:
 
@@ -525,7 +525,7 @@ Deviated well using WellSegment:
     >>> segs = [nodal.WellSegment(md=5000, id=2.441, deviation=0), nodal.WellSegment(md=5000, id=2.441, deviation=45)]
     >>> c_dev = nodal.Completion(segments=segs, tht=100, bht=200)
     >>> nodal.fbhp(thp=500, completion=c_dev, vlpmethod='HB', well_type='gas', qg_mmscfd=5.0, gsg=0.65, cgr=10, qw_bwpd=10, api=45, oil_vis=1.0)
-    923.092017723091
+    926.7968375529219
 
 .. note::
 
@@ -854,14 +854,14 @@ Examples:
     >>> from pyrestoolbox import nodal
     >>> c = nodal.Completion(tid=2.441, length=10000, tht=100, bht=200)
     >>> nodal.fbhp(thp=500, completion=c, vlpmethod='HB', well_type='gas', qg_mmscfd=5.0, gsg=0.65, cgr=10, qw_bwpd=10, api=45, oil_vis=1.0)
-    952.6868477414688
+    954.8384864703888
 
 Comparing all four VLP methods for the same gas well:
 
 .. code-block:: python
 
     >>> nodal.fbhp(thp=500, completion=c, vlpmethod='HB', well_type='gas', qg_mmscfd=5.0, gsg=0.65, cgr=10, qw_bwpd=10, api=45, oil_vis=1.0)
-    952.6868477414688
+    954.8384864703888
     >>> nodal.fbhp(thp=500, completion=c, vlpmethod='WG', well_type='gas', qg_mmscfd=5.0, gsg=0.65, cgr=10, qw_bwpd=10, api=45, oil_vis=1.0)
     1172.8626065704736
     >>> nodal.fbhp(thp=500, completion=c, vlpmethod='GRAY', well_type='gas', qg_mmscfd=5.0, gsg=0.65, cgr=10, qw_bwpd=10, api=45, oil_vis=1.0)