pyrestoolbox 3.1.1__tar.gz → 3.1.2__tar.gz

{pyrestoolbox-3.1.1 → pyrestoolbox-3.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyrestoolbox
-Version: 3.1.1
+Version: 3.1.2
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Rust
 Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
@@ -203,7 +203,7 @@ A set of Gas-Oil relative permeability curves with the LET method
     >>> plt.grid('both')
     >>> plt.plot()
 
-.. image:: https://github.com/mwburgoyne/pyResToolbox/blob/main/pyrestoolbox/docs/img/sgof.png
+.. image:: https://raw.githubusercontent.com/mwburgoyne/pyResToolbox/main/pyrestoolbox/docs/img/sgof.png
     :alt: SGOF Relative Permeability Curves
 
 Or a set of Water-Oil relative permeability curves with the Corey method
@@ -220,7 +220,7 @@ Or a set of Water-Oil relative permeability curves with the Corey method
     >>> plt.grid('both')
     >>> plt.plot()
 
-.. image:: https://github.com/mwburgoyne/pyResToolbox/blob/main/pyrestoolbox/docs/img/swof.png
+.. image:: https://raw.githubusercontent.com/mwburgoyne/pyResToolbox/main/pyrestoolbox/docs/img/swof.png
     :alt: SWOF Relative Permeability Curves
 
 A set of dimensionless pressures for the constant terminal rate Van Everdingin & Hurst aquifer, along with an AQUTAB.INC export for use in ECLIPSE.
@@ -242,7 +242,7 @@ A set of dimensionless pressures for the constant terminal rate Van Everdingin &
     >>> plt.title('Constant Terminal Rate Solution')
     >>> plt.show()
 
-.. image:: https://github.com/mwburgoyne/pyResToolbox/blob/main/pyrestoolbox/docs/img/influence.png
+.. image:: https://raw.githubusercontent.com/mwburgoyne/pyResToolbox/main/pyrestoolbox/docs/img/influence.png
     :alt: Constant Terminal Rate influence tables
 
 Or creating black oil table information for oil
@@ -295,7 +295,7 @@ Or creating black oil table information for oil
     Reservoir Water Compressibility: 2.930237693350768e-06 1/psi
     Reservoir Water Viscosity: 0.3640686136171888 cP
 
-.. image:: https://github.com/mwburgoyne/pyResToolbox/blob/main/pyrestoolbox/docs/img/bot.png
+.. image:: https://raw.githubusercontent.com/mwburgoyne/pyResToolbox/main/pyrestoolbox/docs/img/bot.png
     :alt: Black Oil Properties
 
 And gas
@@ -310,7 +310,7 @@ And gas
     >>> ...
     >>> plt.show()
 
-.. image:: https://github.com/mwburgoyne/pyResToolbox/blob/main/pyrestoolbox/docs/img/dry_gas.png
+.. image:: https://raw.githubusercontent.com/mwburgoyne/pyResToolbox/main/pyrestoolbox/docs/img/dry_gas.png
     :alt: Dry Gas Properties
 
 With ability to generate Live Oil PVTO style table data as well
@@ -384,7 +384,7 @@ With ability to generate Live Oil PVTO style table data as well
     Reservoir Water Compressibility: 2.930237693350768e-06 1/psi
     Reservoir Water Viscosity: 0.3640686136171888 cP
 
-.. image:: https://github.com/mwburgoyne/pyResToolbox/blob/main/pyrestoolbox/docs/img/bot_PVTO.png
+.. image:: https://raw.githubusercontent.com/mwburgoyne/pyResToolbox/main/pyrestoolbox/docs/img/bot_PVTO.png
     :alt: Live Oil Properties
 
 

{pyrestoolbox-3.1.1 → pyrestoolbox-3.1.2}/README.rst

@@ -177,7 +177,7 @@ A set of Gas-Oil relative permeability curves with the LET method
     >>> plt.grid('both')
     >>> plt.plot()
 
-.. image:: https://github.com/mwburgoyne/pyResToolbox/blob/main/pyrestoolbox/docs/img/sgof.png
+.. image:: https://raw.githubusercontent.com/mwburgoyne/pyResToolbox/main/pyrestoolbox/docs/img/sgof.png
     :alt: SGOF Relative Permeability Curves
 
 Or a set of Water-Oil relative permeability curves with the Corey method
@@ -194,7 +194,7 @@ Or a set of Water-Oil relative permeability curves with the Corey method
     >>> plt.grid('both')
     >>> plt.plot()
 
-.. image:: https://github.com/mwburgoyne/pyResToolbox/blob/main/pyrestoolbox/docs/img/swof.png
+.. image:: https://raw.githubusercontent.com/mwburgoyne/pyResToolbox/main/pyrestoolbox/docs/img/swof.png
     :alt: SWOF Relative Permeability Curves
 
 A set of dimensionless pressures for the constant terminal rate Van Everdingin & Hurst aquifer, along with an AQUTAB.INC export for use in ECLIPSE.
@@ -216,7 +216,7 @@ A set of dimensionless pressures for the constant terminal rate Van Everdingin &
     >>> plt.title('Constant Terminal Rate Solution')
     >>> plt.show()
 
-.. image:: https://github.com/mwburgoyne/pyResToolbox/blob/main/pyrestoolbox/docs/img/influence.png
+.. image:: https://raw.githubusercontent.com/mwburgoyne/pyResToolbox/main/pyrestoolbox/docs/img/influence.png
     :alt: Constant Terminal Rate influence tables
 
 Or creating black oil table information for oil
@@ -269,7 +269,7 @@ Or creating black oil table information for oil
     Reservoir Water Compressibility: 2.930237693350768e-06 1/psi
     Reservoir Water Viscosity: 0.3640686136171888 cP
 
-.. image:: https://github.com/mwburgoyne/pyResToolbox/blob/main/pyrestoolbox/docs/img/bot.png
+.. image:: https://raw.githubusercontent.com/mwburgoyne/pyResToolbox/main/pyrestoolbox/docs/img/bot.png
     :alt: Black Oil Properties
 
 And gas
@@ -284,7 +284,7 @@ And gas
     >>> ...
     >>> plt.show()
 
-.. image:: https://github.com/mwburgoyne/pyResToolbox/blob/main/pyrestoolbox/docs/img/dry_gas.png
+.. image:: https://raw.githubusercontent.com/mwburgoyne/pyResToolbox/main/pyrestoolbox/docs/img/dry_gas.png
     :alt: Dry Gas Properties
 
 With ability to generate Live Oil PVTO style table data as well
@@ -358,7 +358,7 @@ With ability to generate Live Oil PVTO style table data as well
     Reservoir Water Compressibility: 2.930237693350768e-06 1/psi
     Reservoir Water Viscosity: 0.3640686136171888 cP
 
-.. image:: https://github.com/mwburgoyne/pyResToolbox/blob/main/pyrestoolbox/docs/img/bot_PVTO.png
+.. image:: https://raw.githubusercontent.com/mwburgoyne/pyResToolbox/main/pyrestoolbox/docs/img/bot_PVTO.png
     :alt: Live Oil Properties
 
 

{pyrestoolbox-3.1.1 → pyrestoolbox-3.1.2}/benchmark_rust_vs_python.py

@@ -64,10 +64,10 @@ print(json.dumps({"elapsed": _elapsed, "value": float(z)}))
 """,
     ),
     (
-        "(b) 100x Z-factors",
-        "[gas.gas_z(p=p, sg=0.7, degf=200, zmethod=z_method.BNS, cmethod=c_method.BNS)\n  for p in np.linspace(500, 5000, 100)]",
+        "(b) 1000x Z-factors",
+        "[gas.gas_z(p=p, sg=0.7, degf=200, zmethod=z_method.BNS, cmethod=c_method.BNS)\n  for p in np.linspace(500, 5000, 1000)]",
         """
-pressures = np.linspace(500, 5000, 100).tolist()
+pressures = np.linspace(500, 5000, 1000).tolist()
 results = [gas.gas_z(p=p, sg=0.7, degf=200, zmethod=z_method.BNS, cmethod=c_method.BNS) for p in pressures]
 print(json.dumps({"elapsed": _elapsed, "value": float(np.mean(results))}))
 """,
@@ -81,10 +81,10 @@ print(json.dumps({"elapsed": _elapsed, "value": float(ug)}))
 """,
     ),
     (
-        "(d) 100x viscosities",
-        "[gas.gas_ug(p=p, sg=0.7, degf=200, zmethod=z_method.BNS, cmethod=c_method.BNS)\n  for p in np.linspace(500, 5000, 100)]",
+        "(d) 1000x viscosities",
+        "[gas.gas_ug(p=p, sg=0.7, degf=200, zmethod=z_method.BNS, cmethod=c_method.BNS)\n  for p in np.linspace(500, 5000, 1000)]",
         """
-pressures = np.linspace(500, 5000, 100).tolist()
+pressures = np.linspace(500, 5000, 1000).tolist()
 results = [gas.gas_ug(p=p, sg=0.7, degf=200, zmethod=z_method.BNS, cmethod=c_method.BNS) for p in pressures]
 print(json.dumps({"elapsed": _elapsed, "value": float(np.mean(results))}))
 """,

{pyrestoolbox-3.1.1 → pyrestoolbox-3.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "pyrestoolbox"
-version = "3.1.1"
+version = "3.1.2"
 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.1.1 → pyrestoolbox-3.1.2}/pyrestoolbox/gas/gas.py

@@ -536,32 +536,60 @@ def _cardano_cubic(c2, c1, c0, flag=0):
         return max(Zs)
     return Zs
 
-def _halley_cubic_vec(c2, c1, c0, max_iter=50, tol=1e-12):
+def _halley_cubic_vec(c2, c1, c0, A=None, B=None, max_iter=50, tol=1e-12):
     """Vectorized Halley solver: solve Z^3+c2*Z^2+c1*Z+c0=0 for max root (vapor Z).
     c2, c1, c0 are 1D arrays of length N. Returns 1D array of Z values.
-    Falls back to _cardano_cubic for any non-converged elements."""
-    N = len(c2)
-    Z = -c2 / 3.0
-    f0 = Z**3 + c2 * Z**2 + c1 * Z + c0
-    Z = np.where(f0 < 0, Z + 1.0, Z)
+    When A and B are provided, solves in Z* = Z - B space (per Aaron Zick's
+    reformulation) where all physical roots lie in (0, 1], giving more
+    robust convergence. Falls back to _cardano_cubic for any bad elements."""
+
+    if A is not None and B is not None:
+        # Z* = Z - B reformulation: Z*³ + d2·Z*² + d1·Z* + d0 = 0
+        # f*(0) = -2B² < 0, f*(1) = A >= 0, so largest root in (0, 1]
+        d2 = 4.0 * B - 1.0
+        d1 = A + 2.0 * B * (B - 2.0)
+        d0 = -2.0 * B * B
+
+        # Start at Z* = 1 (above largest root since f*(1) = A >= 0)
+        Zs = np.ones_like(c2)
+
+        for _ in range(max_iter):
+            f = Zs**3 + d2 * Zs**2 + d1 * Zs + d0
+            fp = 3.0 * Zs**2 + 2.0 * d2 * Zs + d1
+            fpp = 6.0 * Zs + 2.0 * d2
+            safe_fp = np.where(np.abs(fp) < 1e-30, 1e-30, fp)
+            dZ = f / safe_fp
+            denom = safe_fp - 0.5 * dZ * fpp
+            denom = np.where(np.abs(denom) < 1e-30, 1e-30, denom)
+            dZ = f / denom
+            Zs -= dZ
+            if np.max(np.abs(dZ)) < tol:
+                break
+
+        # Convert Z* -> Z; fallback to Cardano in Z space for bad elements
+        Z = Zs + B
+        f = Zs**3 + d2 * Zs**2 + d1 * Zs + d0
+        bad = (np.abs(f) > 1e-6) | (Zs <= 0.0)
+    else:
+        # Legacy path: solve directly in Z space with Cauchy upper bound
+        Z = 1.0 + np.maximum(np.abs(c2), np.maximum(np.abs(c1), np.abs(c0)))
+
+        for _ in range(max_iter):
+            f = Z**3 + c2 * Z**2 + c1 * Z + c0
+            fp = 3.0 * Z**2 + 2.0 * c2 * Z + c1
+            fpp = 6.0 * Z + 2.0 * c2
+            safe_fp = np.where(np.abs(fp) < 1e-30, 1e-30, fp)
+            dZ = f / safe_fp
+            denom = safe_fp - 0.5 * dZ * fpp
+            denom = np.where(np.abs(denom) < 1e-30, 1e-30, denom)
+            dZ = f / denom
+            Z -= dZ
+            if np.max(np.abs(dZ)) < tol:
+                break
 
-    for _ in range(max_iter):
         f = Z**3 + c2 * Z**2 + c1 * Z + c0
-        fp = 3.0 * Z**2 + 2.0 * c2 * Z + c1
-        fpp = 6.0 * Z + 2.0 * c2
-        # Protect against zero derivatives
-        safe_fp = np.where(np.abs(fp) < 1e-30, 1e-30, fp)
-        dZ = f / safe_fp
-        denom = safe_fp - 0.5 * dZ * fpp
-        denom = np.where(np.abs(denom) < 1e-30, 1e-30, denom)
-        dZ = f / denom
-        Z -= dZ
-        if np.max(np.abs(dZ)) < tol:
-            break
+        bad = (np.abs(f) > 1e-6) | (Z < 0.0)
 
-    # Check residuals and fall back to Cardano for any bad elements
-    f = Z**3 + c2 * Z**2 + c1 * Z + c0
-    bad = np.abs(f) > 1e-6
     if np.any(bad):
         bad_idx = np.where(bad)[0]
         for idx in bad_idx:
@@ -766,7 +794,7 @@ def gas_z(
         c0 = -(A * B - B**2 - B**3)
 
         # Solve all cubics at once - get max (vapor) root
-        Z_raw = _halley_cubic_vec(c2, c1_coeff, c0)    # (N,)
+        Z_raw = _halley_cubic_vec(c2, c1_coeff, c0, A=A, B=B)    # (N,)
 
         # Fugacity-based root selection for sub-critical conditions
         # When 3 real roots exist, the thermodynamically stable phase

{pyrestoolbox-3.1.1 → pyrestoolbox-3.1.2}/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = pyrestoolbox
-version = 3.1.1
+version = 3.1.2
 author = Mark W. Burgoyne
 author_email = mark.w.burgoyne@gmail.com
 description = pyResToolbox - A collection of Reservoir Engineering Utilities

{pyrestoolbox-3.1.1 → pyrestoolbox-3.1.2}/setup.py

@@ -12,7 +12,7 @@ with open(os.path.join(ROOT, 'README.rst'), 'r', encoding='utf-8') as f:
 setup(
     name='pyrestoolbox',
     include_package_data=True,
-    version='3.1.1',  # Ideally should be same as your GitHub release tag version
+    version='3.1.2',  # Ideally should be same as your GitHub release tag version
     packages=find_packages(exclude=['pyrestoolbox.tests', 'pyrestoolbox.tests.*']),
     description='pyResToolbox - A collection of Reservoir Engineering Utilities',
     license="GNU General Public License v3 or later (GPLv3+)",

{pyrestoolbox-3.1.1 → pyrestoolbox-3.1.2}/src/zfactor/mod.rs

@@ -288,37 +288,46 @@ fn cardano_cubic(c2: f64, c1: f64, c0: f64, flag: i32) -> f64 {
     }
 }
 
-/// Halley's method for finding max root of cubic z^3 + c2*z^2 + c1*z + c0 = 0
-fn halley_cubic(c2: f64, c1: f64, c0: f64) -> f64 {
-    let mut z = -c2 / 3.0;
-    let f0 = z * z * z + c2 * z * z + c1 * z + c0;
-    if f0 < 0.0 {
-        z += 1.0;
-    }
+/// Halley's method for finding max root of cubic z^3 + c2*z^2 + c1*z + c0 = 0,
+/// using Z* = Z - B transformation (per Aaron Zick's reformulation).
+/// For any standard cubic EOS with non-negative A, all physical Z* roots
+/// lie in (0, 1], eliminating negative/huge roots and guaranteeing convergence.
+/// Returns Z (not Z*), i.e. the B offset is added back before returning.
+fn halley_cubic_zstar(a_mix: f64, b_mix: f64) -> f64 {
+    // Z* cubic: Z*³ + d2·Z*² + d1·Z* + d0 = 0
+    // where f*(0) = d0 = -2B² < 0 and f*(1) = A >= 0
+    let d2 = 4.0 * b_mix - 1.0;
+    let d1 = a_mix + 2.0 * b_mix * (b_mix - 2.0);
+    let d0 = -2.0 * b_mix * b_mix;
+
+    // Start at Z* = 1 where f* = A >= 0 (above largest root).
+    let mut zs = 1.0_f64;
 
     for _ in 0..50 {
-        let f = z * z * z + c2 * z * z + c1 * z + c0;
-        let fp = 3.0 * z * z + 2.0 * c2 * z + c1;
-        let fpp = 6.0 * z + 2.0 * c2;
+        let f = zs * zs * zs + d2 * zs * zs + d1 * zs + d0;
+        let fp = 3.0 * zs * zs + 2.0 * d2 * zs + d1;
+        let fpp = 6.0 * zs + 2.0 * d2;
 
         let fp_safe = if fp.abs() < 1e-30 { 1e-30 } else { fp };
         let dz = f / fp_safe;
         let denom = fp_safe - 0.5 * dz * fpp;
         let denom_safe = if denom.abs() < 1e-30 { 1e-30 } else { denom };
         let dz_final = f / denom_safe;
-        z -= dz_final;
+        zs -= dz_final;
         if dz_final.abs() < 1e-12 {
             break;
         }
     }
 
-    // Verify convergence
-    let f = z * z * z + c2 * z * z + c1 * z + c0;
-    if f.abs() > 1e-6 {
-        // Fallback to Cardano
+    // Verify convergence; fallback to Cardano in Z space if needed
+    let f = zs * zs * zs + d2 * zs * zs + d1 * zs + d0;
+    if f.abs() > 1e-6 || zs <= 0.0 {
+        let c2 = -(1.0 - b_mix);
+        let c1 = a_mix - 3.0 * b_mix * b_mix - 2.0 * b_mix;
+        let c0 = -(a_mix * b_mix - b_mix * b_mix - b_mix * b_mix * b_mix);
         return cardano_cubic(c2, c1, c0, 1);
     }
-    z
+    zs + b_mix
 }
 
 fn bns_zfactor_core(
@@ -381,28 +390,29 @@ fn bns_zfactor_core(
         b_mix += zi[i] * bi[i];
     }
 
-    // Cubic coefficients: Z^3 + c2*Z^2 + c1*Z + c0 = 0
-    let c2 = -(1.0 - b_mix);
-    let c1 = a_mix - 3.0 * b_mix * b_mix - 2.0 * b_mix;
-    let c0 = -(a_mix * b_mix - b_mix * b_mix - b_mix * b_mix * b_mix);
-
-    // Solve cubic - get max (vapor) root
-    let z_max = halley_cubic(c2, c1, c0);
+    // Solve cubic in Z* = Z - B space (Aaron Zick reformulation)
+    let z_max = halley_cubic_zstar(a_mix, b_mix);
 
-    // Check for 3-root case (fugacity-based root selection)
-    let p_d = (3.0 * c1 - c2 * c2) / 3.0;
-    let q_d = (2.0 * c2 * c2 * c2 - 9.0 * c2 * c1 + 27.0 * c0) / 27.0;
+    // Fugacity-based root selection for sub-critical conditions.
+    // Use Z* cubic discriminant to check for 3-root case.
+    let d2 = 4.0 * b_mix - 1.0;
+    let d1 = a_mix + 2.0 * b_mix * (b_mix - 2.0);
+    let d0 = -2.0 * b_mix * b_mix;
+    let p_d = (3.0 * d1 - d2 * d2) / 3.0;
+    let q_d = (2.0 * d2 * d2 * d2 - 9.0 * d2 * d1 + 27.0 * d0) / 27.0;
     let disc = q_d * q_d / 4.0 + p_d * p_d * p_d / 27.0;
 
     let z_selected = if disc < -1e-15 {
-        // 3 real roots - find min root via deflation
-        let b_q = c2 + z_max;
-        let c_q = c1 + z_max * b_q;
+        // 3 real roots — find min root via deflation in Z* space
+        let zs_max = z_max - b_mix; // convert back to Z*
+        let b_q = d2 + zs_max;
+        let c_q = d1 + zs_max * b_q;
         let det = (b_q * b_q - 4.0 * c_q).max(0.0);
-        let z_min = (-b_q - det.sqrt()) / 2.0;
+        let zs_min = (-b_q - det.sqrt()) / 2.0;
+        let z_min = zs_min + b_mix; // convert to Z
 
-        // Fugacity comparison (Gibbs criterion)
-        if z_min > b_mix {
+        // Fugacity comparison (Gibbs criterion); Z > B ↔ Z* > 0
+        if zs_min > 0.0 {
             let sqrt2: f64 = std::f64::consts::SQRT_2;
             let s2p1 = 1.0 + sqrt2;
             let s2m1 = sqrt2 - 1.0;