pyrestoolbox 3.0.4__tar.gz → 3.0.5__tar.gz

pyrestoolbox-3.0.5/MANIFEST.in

@@ -0,0 +1,8 @@
+include README.rst
+include LICENSE
+recursive-include pyrestoolbox *.py *.xlsx *.rst *.ipynb *.png
+global-exclude *.pyc
+global-exclude *Zone.Identifier
+prune pyrestoolbox/tests
+prune pyrestoolbox/docs/.ipynb_checkpoints
+recursive-exclude * __pycache__

{pyrestoolbox-3.0.4/pyrestoolbox.egg-info → pyrestoolbox-3.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyrestoolbox
-Version: 3.0.4
+Version: 3.0.5
 Summary: pyResToolbox - A collection of Reservoir Engineering Utilities
 Home-page: https://github.com/mwburgoyne/pyResToolbox
 Author: Mark W. Burgoyne

{pyrestoolbox-3.0.4 → pyrestoolbox-3.0.5}/pyrestoolbox/brine/brine.py

@@ -24,7 +24,7 @@ Brine property calculations with three models.
 
 Functions
 ---------
-brine_props         Methane-saturated brine properties (Bw, density, viscosity, Cw, Rs)
+brine_props         Methane-saturated brine properties (Bw, density, viscosity, [Cw_usat, Cw_sat], Rs)
 make_pvtw_table     Water PVT table generation (backward-compatible wrapper)
 
 Classes
@@ -361,12 +361,15 @@ def brine_props(p: float, degf: float, wt: float=0, ch4_sat: float=0, metric: bo
     bw = Bw  # rb/stb (dimensionless ratio, same in both unit systems)
     lden = rhobtpbch4  # sg (g/cm3)
     visw = ub_tpm  # cP
-    cw = cw_new  # 1/psi
+    cwu_psi = 1 / (145.038 * (1 / cwu))  # Undersaturated compressibility in psi-1
+    cws_psi = cw_new  # Saturated compressibility in psi-1
     rsw = rsw_new_oilfield  # scf/stb
 
     if metric:
-        cw = cw * INVPSI_TO_INVBAR  # 1/psi -> 1/bar
+        cw = [cwu_psi * INVPSI_TO_INVBAR, cws_psi * INVPSI_TO_INVBAR]  # 1/bar
         rsw = rsw * SCF_PER_STB_TO_SM3_PER_SM3  # scf/stb -> sm3/sm3
+    else:
+        cw = [cwu_psi, cws_psi]  # 1/psi
 
     return (bw, lden, visw, cw, rsw)
 
@@ -1686,10 +1689,10 @@ class SoreideWhitson:
         #   Viscosity: Mao-Duan (2009) via brine_props
         # ================================================================
         # brine_props still needed for viscosity, compressibility, Bw, Rsw
-        bw_base, den_base_sg, vis_base_cP, cw_base, rsw_base = brine_props(
+        bw_base, den_base_sg, vis_base_cP, _, rsw_base = brine_props(
             p=psia, degf=degf, wt=wt, ch4_sat=0
         )
-        bw_fw, den_fw_sg, vis_fw_cP, cw_fw, rsw_fw = brine_props(
+        bw_fw, den_fw_sg, vis_fw_cP, _, rsw_fw = brine_props(
             p=psia, degf=degf, wt=0, ch4_sat=0
         )
 

{pyrestoolbox-3.0.4 → pyrestoolbox-3.0.5}/pyrestoolbox/docs/brine.rst

@@ -91,8 +91,8 @@ pyrestoolbox.brine.brine_props
      - float
      - Viscosity (cP)
    * - [3]
-     - float
-     - Compressibility (1/psi, or 1/barsa if metric=True)
+     - list
+     - Compressibility [undersaturated, saturated] (1/psi, or 1/barsa if metric=True). The undersaturated value (Cw[0]) is the isothermal compressibility of the brine at constant dissolved gas content. The saturated value (Cw[1]) is a pseudo-compressibility representing the average compressibility of the brine and differentially evolved gas system, accounting for both liquid compression and gas exsolution volume changes
    * - [4]
      - float
      - Rsw — solution gas-water ratio (scf/stb, or sm3/sm3 if metric=True)
@@ -106,17 +106,19 @@ Examples:
     >>> print('Bw:', bw)
     >>> print('SGw:', lsg)
     >>> print('Visw:', visw)
-    >>> print('Cw:', cw)
+    >>> print('Cw_usat:', cw[0])
+    >>> print('Cw_sat:', cw[1])
     >>> print('Rsw:', rsw)
     Bw: 1.0152007040056148
     SGw: 0.9950108179684295
     Visw: 0.4994004662758671
-    Cw: 0.0001539690974662865
+    Cw_usat: 2.969627494768876e-06
+    Cw_sat: 0.0001539690974662865
     Rsw: 1.2540982731813703
 
 .. note::
 
-    When ``metric=True``, Cw is returned in 1/barsa (instead of 1/psi) and Rsw in sm3/sm3 (instead of scf/stb).
+    When ``metric=True``, Cw values are returned in 1/barsa (instead of 1/psi) and Rsw in sm3/sm3 (instead of scf/stb).
     Bw (rb/stb), density (SG), and viscosity (cP) are unchanged by the unit system.
 
 pyrestoolbox.brine.CO2_Brine_Mixture
@@ -187,9 +189,9 @@ pyrestoolbox.brine.CO2_Brine_Mixture
    * - .Cf_usat
      - float
      - Brine undersaturated compressibility (1/Bar or 1/psi)
-   * - .Cf_ssat
+   * - .Cf_sat
      - float
-     - Brine saturated compressibility (1/Bar or 1/psi). Requires cw_sat input to be set True to calculate
+     - Brine saturated pseudo-compressibility (1/Bar or 1/psi). Represents the average compressibility of the brine and differentially evolved gas system, accounting for both liquid compression and gas exsolution. Requires cw_sat input to be set True to calculate
 
                 
 Examples:
@@ -272,7 +274,7 @@ Optionally exports ECLIPSE PVTW keyword file and Excel spreadsheet.
      - Description
    * - table
      - DataFrame
-     - Pressure, Bw, Density, Viscosity, Cw, Rsw
+     - Pressure, Bw, Density, Viscosity, Cw_usat, Cw_sat, Rsw
    * - pref
      - float
      - Reference pressure (psia, or barsa if metric=True)
@@ -280,8 +282,8 @@ Optionally exports ECLIPSE PVTW keyword file and Excel spreadsheet.
      - float
      - Bw at reference pressure (rb/stb)
    * - cw_ref
-     - float
-     - Compressibility at reference pressure (1/psi, or 1/bar if metric=True)
+     - list
+     - Compressibility [undersaturated, saturated] at reference pressure (1/psi, or 1/bar if metric=True)
    * - visw_ref
      - float
      - Viscosity at reference pressure (cP)
@@ -301,7 +303,7 @@ Examples:
     >>> result['bw_ref']
     1.027589195773527
     >>> result['cw_ref']
-    3.0887176266534516e-06
+    [3.0887176266534516e-06, 3.0887176266534516e-06]
     >>> result['visw_ref']
     0.3083544960904146
 
@@ -421,7 +423,7 @@ based on the gas specific gravity using constrained exponential decay to match t
      - Brine undersaturated compressibility (1/Bar or 1/psi)
    * - .Cf_sat
      - float
-     - Brine saturated compressibility (1/Bar or 1/psi). Requires cw_sat input to be set True to calculate
+     - Brine saturated pseudo-compressibility (1/Bar or 1/psi). Represents the average compressibility of the brine and differentially evolved gas system, accounting for both liquid compression and gas exsolution. Requires cw_sat input to be set True to calculate
    * - .gas_comp
      - dict
      - Normalized gas composition used (including estimated HC split from SG)

{pyrestoolbox-3.0.4 → pyrestoolbox-3.0.5}/pyrestoolbox/docs/changelist.rst

@@ -1,3 +1,15 @@
+Changelist in 3.0.5:
+
+- **brine_props()**: Compressibility return changed from a scalar (saturated only) to a ``[cw_usat, cw_sat]`` list. The undersaturated value (Spivey Eq 4.32) is the isothermal compressibility at constant dissolved gas content. The saturated value (Spivey Eq 4.35) is a pseudo-compressibility of the brine and differentially evolved gas system. Previously only the saturated value was returned.
+- **oil_co()**: Changed from saturated pseudo-compressibility (``Co = -1/Bo * (dBo/dp - Bg * dRs/dp)``) to undersaturated compressibility (``Co = -1/Bo * dBo/dp`` at constant Rs). Rs is held at the equilibrium value for the specified pressure, yielding the isothermal liquid-phase compressibility without mixing in differentially evolved gas volume. Values below Pb are now smaller and physically consistent with above-Pb values.
+- **oil_co() co_sat parameter**: New ``co_sat=False`` parameter. When ``True``, returns ``[co_usat, co_sat]`` list. Saturated compressibility uses Perrine's definition: ``co_sat = -(1/Bo)*dBo/dp + (Bg/Bo)*dRs/dp``, a pseudo-compressibility including gas evolution effects. Above Pb, both values are equal. Backward compatible — default returns a float.
+- **oil_bt()**: New function returning total two-phase oil FVF: ``Bt = Bo + (Rsi - Rs) * Bg``. Above Pb returns Bo. Useful for material balance and reservoir voidage calculations.
+- **oil_matbal() metric cw/cf fix**: Fixed bug where ``cw`` and ``cf`` in 1/bar were not converted to 1/psi when ``metric=True``, causing the Efw term to be off by ~14.5x. Regression bounds for ``cw``/``cf`` are also now correctly unit-converted.
+- **CO2_Brine_Mixture.Cf_sat** and **SoreideWhitson.Cf_sat**: Documentation clarified that these are pseudo-compressibilities representing the average compressibility of the brine and differentially evolved gas system.
+- **make_pvtw_table()**: Table now includes both ``Cw_usat`` and ``Cw_sat`` columns. ``cw_ref`` is now a ``[usat, sat]`` list. PVTW keyword export uses undersaturated compressibility.
+- **make_bot_og()**: Water compressibility (``cw`` key) now uses undersaturated value from ``brine_props()``.
+- 603 validation tests (up from 588 in 3.0.4).
+
 Changelist in 3.0.4:
 
 - **VLP performance**: Eliminated duplicate Z-factor calculations in all 8 VLP method functions. ``_gas_viscosity()`` now accepts a pre-computed Z-factor, avoiding a redundant Hall-Yarborough solve on every segment iteration. Combined with pre-computing Sutton critical properties (Tc/Pc) once per VLP function call instead of recalculating on every segment step. Delivers ~11% speedup on ``operating_point()`` and ``outflow_curve()`` calls.

{pyrestoolbox-3.0.4 → pyrestoolbox-3.0.5}/pyrestoolbox/docs/matbal.rst

@@ -257,7 +257,7 @@ Havlena-Odeh oil material balance for OOIP estimation. Computes underground with
      - Initial water saturation (fraction, default 0)
    * - cw
      - float
-     - Water compressibility (1/psi | 1/bar, default 0)
+     - Water compressibility (1/psi | 1/bar, default 0). See compressibility guidance below
    * - rsmethod
      - str
      - Solution GOR method (default 'VELAR')
@@ -370,6 +370,25 @@ Tabulated PVT Example:
     82793519.84914012
 
 
+.. note:: **Compressibility Guidance**
+
+   The ``cw`` parameter controls how water compressibility is treated in the formation/water expansion term (Efw). Two approaches are common:
+
+   - **Undersaturated (liquid-phase) compressibility**: Use ``cw_usat`` from ``brine.brine_props()``, which is the isothermal compressibility of brine at constant dissolved gas content. Appropriate when the material balance tracks free gas volumes separately, or when the water does not evolve dissolved gas over the depletion range.
+
+   - **Saturated (pseudo) compressibility**: Use ``cw_sat`` from ``brine.brine_props()``, which includes the volume of differentially evolved gas. Appropriate when no separate water-gas tracking is performed. Dissolved gas in water can contribute compressibility as large as or larger than the liquid-phase value alone (Ramey, 1964).
+
+   To compute ``cw`` from brine properties:
+
+   .. code-block:: python
+
+       >>> from pyrestoolbox import brine
+       >>> props = brine.brine_props(p=4000, degf=220, wt=3)
+       >>> cw_usat, cw_sat = props['cw']  # [undersaturated, saturated]
+
+   Similarly, ``oil.oil_co(co_sat=True)`` returns ``[co_usat, co_sat]`` — the undersaturated value is the liquid-phase compressibility, while the saturated value includes gas evolution effects (Perrine's definition).
+
+
 Class Objects
 ======================
 

{pyrestoolbox-3.0.4 → pyrestoolbox-3.0.5}/pyrestoolbox/docs/oil.rst

@@ -46,9 +46,9 @@ pyResToolBox uses class objects to track calculation options through the functio
         + 'VALMC': Valko-McCain Correlation (2003) - Only for oil_rs_bub (Rs at Pb)
    * - comethod
      - co_method
-     - Method for calculating oil compressibility. Defaults to 'EXPLT'.  
+     - Method for calculating undersaturated oil compressibility. Defaults to 'EXPLT'.
        Options are:
-        + 'EXPLT': Explicit calculation with numerical derivatives assessed and calculation via co = -1/bo*(dbodp - bg*drsdp/5.61458). 
+        + 'EXPLT': Explicit calculation with numerical derivatives via co = -1/bo*dBo/dp at constant Rs.
    * - denomethod
      - deno_method
      - Method for calculating oil density. Defaults to 'SWMH'
@@ -152,7 +152,9 @@ Function List
    * - Oil GOR at P
      - `pyrestoolbox.oil.oil_rs`_  
    * - Oil Compressibility
-     - `pyrestoolbox.oil.oil_co`_  
+     - `pyrestoolbox.oil.oil_co`_
+   * - Total Two-Phase Oil FVF
+     - `pyrestoolbox.oil.oil_bt`_
    * - Oil Density
      - `pyrestoolbox.oil.oil_deno`_
    * - Oil Formation Volume Factor
@@ -546,9 +548,14 @@ pyrestoolbox.oil.oil_co
 
 .. code-block:: python
 
-    oil_co(p, api,  degf, sg_sp =0, sg_g =0, pb =0, rsb =0, comethod='EXPLT', zmethod='DAK', rsmethod='VELAR', cmethod='PMC', denomethod='SWMH', bomethod='MCAIN', pbmethod='VALMC', metric = False) -> float
+    oil_co(p, api, degf, sg_sp=0, sg_g=0, pb=0, rsb=0, co_sat=False, comethod='EXPLT', zmethod='DAK', rsmethod='VELAR', cmethod='PMC', denomethod='SWMH', bomethod='MCAIN', pbmethod='VALMC', metric=False) -> float or list
+
+Returns oil compressibility (1/psi, or 1/barsa if metric=True).
+
+By default (``co_sat=False``) returns **undersaturated** compressibility calculated with ``Co = -1/Bo * dBo/dp`` at constant Rs, using correlation values and their numerical derivatives. Rs is held at the equilibrium value for the specified pressure — rsb when above Pb, or the correlation value at p when below Pb. This yields the isothermal compressibility of the liquid oil phase at its current dissolved gas content, without mixing in the volume of differentially evolved gas.
+
+When ``co_sat=True``, returns a ``[co_usat, co_sat]`` list. The **saturated** compressibility uses Perrine's definition: ``co_sat = -(1/Bo)*dBo/dp + (Bg/Bo)*dRs/dp``, where both Bo and Rs vary with pressure. This is a pseudo-compressibility representing the average compressibility of the oil and its differentially evolved gas. Above Pb, ``co_sat`` equals ``co_usat`` (no gas evolution).
 
-Returns oil compressibility (1/psi, or 1/barsa if metric=True) calculated with Co = -1/Bo *[dBodp - Bg*dRsdp], using correlation values and their numerical derivatives.
 At least one of sg_g and sg_sp must be supplied. This function will make simple assumption to estimate missing gas sg if only one is provided.
 Either pb, rsb or both need to be specified. If one is missing, the other will be calculated from correlation
 
@@ -581,6 +588,9 @@ Either pb, rsb or both need to be specified. If one is missing, the other will b
    * - rsb
      - float
      - Original solution GOR at original bubble point pressure (scf/stb, or sm3/sm3 if metric=True)
+   * - co_sat
+     - bool
+     - If True, return ``[co_usat, co_sat]`` list. Default False (returns float)
    * - comethod
      - string or co_method
      - The method of Compressibility calculation to be employed. `Calculation Methods and Class Objects`_.
@@ -613,21 +623,119 @@ Either pb, rsb or both need to be specified. If one is missing, the other will b
    * - Name
      - Type
      - Description
-   * -
+   * - co (co_sat=False)
      - float
-     - Oil compressibility (1/psi, or 1/barsa if metric=True)
+     - Undersaturated oil compressibility (1/psi, or 1/barsa if metric=True)
+   * - [co_usat, co_sat] (co_sat=True)
+     - list
+     - ``[undersaturated, saturated]`` compressibility (1/psi, or 1/barsa if metric=True)
 
 
 Examples:
 
 .. code-block:: python
 
-    >>> oil.oil_co(p = 4500, api = 47, degf = 180, sg_sp = 0.72, rsb = 2750)
-    8.430807614802478e-05
+    >>> oil.oil_co(p=6000, api=47, degf=180, sg_sp=0.72, rsb=2750, pb=4945)
+    3.63915926110187e-05
+
+    >>> oil.oil_co(p=2000, api=47, degf=180, sg_sp=0.72, rsb=2750, pb=4945)
+    1.0122640715155418e-05
+
+    >>> oil.oil_co(p=2000, api=47, degf=180, sg_sp=0.72, rsb=2750, pb=4945, co_sat=True)
+    [1.0122640715155418e-05, 0.0002315283893081275]
+
+
+pyrestoolbox.oil.oil_bt
+=====================
+
+.. code-block:: python
+
+    oil_bt(p, api, degf, sg_sp=0, sg_g=0, pb=0, rsb=0, rsi=0, zmethod='DAK', rsmethod='VELAR', cmethod='PMC', denomethod='SWMH', bomethod='MCAIN', pbmethod='VALMC', metric=False) -> float
+
+Returns total two-phase oil formation volume factor Bt (rb/stb, or rm3/sm3 if metric=True).
+
+``Bt = Bo + (Rsi - Rs) * Bg``
+
+Above Pb, Rs = Rsi so Bt = Bo. Below Pb, Bt accounts for the reservoir volume of both the liquid oil and the gas that has evolved from it relative to the original solution GOR.
+
+At least one of sg_g and sg_sp must be supplied.
+Either pb, rsb or both need to be specified.
+
+
+.. list-table:: Inputs
+   :widths: 10 15 40
+   :header-rows: 1
+
+   * - Parameter
+     - Type
+     - Description
+   * - p
+     - float
+     - Pressure (psia, or barsa if metric=True)
+   * - api
+     - float
+     - Density of stock tank liquid (API)
+   * - degf
+     - float
+     - Oil Temperature (deg F, or deg C if metric=True)
+   * - sg_sp
+     - float
+     - Separator gas gravity (relative to air)
+   * - sg_g
+     - float
+     - Weighted average specific gravity of surface gas (relative to air)
+   * - pb
+     - float
+     - Bubble point pressure (psia, or barsa if metric=True)
+   * - rsb
+     - float
+     - Solution GOR at bubble point (scf/stb, or sm3/sm3 if metric=True)
+   * - rsi
+     - float
+     - Initial solution GOR (scf/stb, or sm3/sm3 if metric=True). Default 0 = use rsb
+   * - zmethod
+     - string or z_method
+     - The method of gas z-factor calculation. `Calculation Methods and Class Objects`_.
+   * - rsmethod
+     - string or rs_method
+     - The method of Rs calculation. `Calculation Methods and Class Objects`_.
+   * - cmethod
+     - string or c_method
+     - The method of critical gas property calculation. `Calculation Methods and Class Objects`_.
+   * - denomethod
+     - string or deno_method
+     - The method of live oil density calculation. `Calculation Methods and Class Objects`_.
+   * - bomethod
+     - string or bo_method
+     - The method of Bo calculation. `Calculation Methods and Class Objects`_.
+   * - pbmethod
+     - string or pb_method
+     - The method of Pb calculation. `Calculation Methods and Class Objects`_.
+   * - metric
+     - bool
+     - Use Eclipse METRIC units for inputs/outputs. Default False
+
+.. list-table:: Returns
+   :widths: 10 15 40
+   :header-rows: 1
+
+   * - Name
+     - Type
+     - Description
+   * -
+     - float
+     - Total two-phase oil FVF (rb/stb, or rm3/sm3 if metric=True)
+
+Examples:
+
+.. code-block:: python
+
+    >>> oil.oil_bt(p=2000, api=47, degf=180, sg_sp=0.72, rsb=2750, pb=4945)
+    4.162163176179142
+
+    >>> oil.oil_bt(p=6000, api=47, degf=180, sg_sp=0.72, rsb=2750, pb=4945)
+    2.291191400872878
 
-    >>> oil.oil_co(p=2000, api=47, degf=180, sg_sp =0.72, rsb =2750, pb=4945)
-    0.0002311385007013396
-    
 
 pyrestoolbox.oil.oil_deno
 ==============================
@@ -1036,7 +1144,7 @@ If user species Pb or Rsb only, the corresponding property will be calculated. I
      - Water density at Pi (lb/cuft)
    * - 'cw'
      - float
-     - Water compressibility at Pi (1/psi)
+     - Water undersaturated compressibility at Pi (1/psi)
    * - 'uw'
      - float
      - Water viscosity at Pi (cP)

{pyrestoolbox-3.0.4 → pyrestoolbox-3.0.5}/pyrestoolbox/docs/simtools.rst

@@ -1210,7 +1210,7 @@ Creates data required for Oil-Gas-Water black oil tables (PVDO, PVDG, optionally
      - Water density at Pi (lb/cuft, or kg/m3 if metric)
    * - 'cw'
      - float
-     - Water compressibility at Pi (1/psi, or 1/bar if metric)
+     - Water undersaturated compressibility at Pi (1/psi, or 1/bar if metric)
    * - 'uw'
      - float
      - Water viscosity at Pi (cP)

{pyrestoolbox-3.0.4 → pyrestoolbox-3.0.5}/pyrestoolbox/matbal/matbal.py

@@ -451,6 +451,9 @@ def oil_matbal(p, Np, degf, api=0, sg_sp=0, sg_g=0, pb=0, rsb=0,
         degf_field = degc_to_degf(degf)
         pb_field = pb * BAR_TO_PSI if pb > 0 else 0
         rsb_field = rsb * SM3_PER_SM3_TO_SCF_PER_STB if rsb > 0 else 0
+        # Convert compressibilities from 1/bar to 1/psi
+        cw = cw / BAR_TO_PSI   # 1/bar → 1/psi
+        cf = cf / BAR_TO_PSI   # 1/bar → 1/psi
     else:
         p_field = p
         degf_field = degf
@@ -567,6 +570,14 @@ def oil_matbal(p, Np, degf, api=0, sg_sp=0, sg_g=0, pb=0, rsb=0,
 
         param_names = list(regress.keys())
         bounds = [regress[k] for k in param_names]
+
+        # Convert compressibility regression bounds from 1/bar to 1/psi when metric
+        if metric:
+            bounds = [
+                (lo / BAR_TO_PSI, hi / BAR_TO_PSI) if k in ('cw', 'cf') else (lo, hi)
+                for k, (lo, hi) in zip(param_names, bounds)
+            ]
+
         base_vals = {'m': m, 'cf': cf, 'cw': cw, 'sw_i': sw_i}
 
         # Initial guess: use passed value if within bounds, else midpoint
@@ -605,7 +616,14 @@ def oil_matbal(p, Np, degf, api=0, sg_sp=0, sg_g=0, pb=0, rsb=0,
         cf = base_vals['cf']
         cw = base_vals['cw']
         sw_i = base_vals['sw_i']
-        regressed_result = {k: float(v) for k, v in zip(param_names, opt_result.x)}
+
+        # Report regressed values back in user's unit system
+        regressed_result = {}
+        for k, v in zip(param_names, opt_result.x):
+            if metric and k in ('cw', 'cf'):
+                regressed_result[k] = float(v * BAR_TO_PSI)  # 1/psi → 1/bar
+            else:
+                regressed_result[k] = float(v)
 
     # Final computation with (possibly regressed) params
     ooip, Efw, denom, valid = _compute_result(m, cf, cw, sw_i)