diff --git a/petrolib/acoustic_geomech.py b/petrolib/acoustic_geomech.py index dc739ef..3aceab2 100644 --- a/petrolib/acoustic_geomech.py +++ b/petrolib/acoustic_geomech.py @@ -16,6 +16,144 @@ (Vp,Vs), (lambda,mu), (E,nu) return them as a tuple in the documented order -- an order-collision hazard the corpus hits both ways, so the order is fixed and documented here and facades map to it explicitly. + +References +---------- +Complete citations for the source tags used in this module (SPWLA journal +*Petrophysics*): + +src2014_02/article5_thermal_conductivity_velocity -- Article 5: Thermal Conductivity Estimation + From Elastic-Wave Velocity - Application of a Petrographic-Coded Model. Nina Gegenhuber, Jurgen + Schon (2014). Petrophysics Vol. 55, No. 1 (February 2014), pp. 51-56. DOI: none assigned (this + issue predates SPWLA DOI assignment). +src2014_06/article1_bazhenov_rock_physics -- Article 1: A Case Study about Formation Evaluation and + Rock Physics Modeling of the Bazhenov Shale. Pavel Kulyapin and Tatiana F. Sokolova (2014). + Petrophysics Vol. 55, No. 3 (June 2014), pp. 211-218. DOI: none assigned (this issue predates + SPWLA DOI assignment). +src2014_08/article6_siliceous_ooze_petrophysics -- Article 6: Petrophysical Analysis of Siliceous- + Ooze Sediments, More Basin, Norwegian Sea. Ahmed Awadalkarim, Morten Kanne Sorensen, Ida Lykke + Fabricius (2014). Petrophysics Vol. 55, No. 4 (August 2014), pp. 333-348. DOI: none assigned + (this issue predates SPWLA DOI assignment). +src2015_10/article1_acoustic_anisotropy -- Article 1: Untangling Acoustic Anisotropy. Market, + Mejia, Mutlu, Shahri, Tudge (2015). Petrophysics Vol. 56, No. 5 (October 2015), pp. 420-439. DOI: + none assigned (this issue predates SPWLA DOI assignment). +src2016_04/article5_acoustic_anisotropy_no_stoneley -- Article 5: Method for Acoustic Anisotropy + Interpretation in Shales When the Stoneley-Wave Velocity is Missing. Gu, Quirein, Murphy, Rivera + Barraza, Ou (2016). Petrophysics Vol. 57, No. 2 (April 2016), pp. 140-156. DOI: none assigned + (this issue predates SPWLA DOI assignment). +src2016_10/article5_microfracturing_insitu_stress -- Article 5: How Can Microfracturing Improve + Reservoir Management?. Malik, Jones, Boratko (2016). Petrophysics Vol. 57, No. 5 (October 2016), + pp. 492-507. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2016_12/article1_shale_fracturing_ml -- Article 1: Shale Fracturing Characterization and + Optimization by Using Anisotropic Acoustic Interpretation, 3D Fracture Modeling, and Supervised + Machine Learning. Gu, Gokaraju, Chen, Quirein (2016). Petrophysics Vol. 57, No. 6 (December + 2016), pp. 573-587. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2016_12/article2_orthorhombic_geomechanics -- Article 2: Geomechanics of Orthorhombic Media. + Far, Quirein, Mekic (2016). Petrophysics Vol. 57, No. 6 (December 2016), pp. 588-596. DOI: none + assigned (this issue predates SPWLA DOI assignment). +src2016_12/article5_ultrasonic_permeability_carbonate -- Article 5: Permeability Estimation Using + Ultrasonic Borehole Image Logs in Dual-Porosity Carbonate Reservoirs. Menezes de Jesus, Martins + Compan, Surmas (2016). Petrophysics Vol. 57, No. 6 (December 2016), pp. 620-637. DOI: none + assigned (this issue predates SPWLA DOI assignment). +src2017_04/article4_t1t2_affinity_gassmann -- Article 4: Low-Field NMR Spectrometry of Chalk and + Argillaceous Sandstones: Rock-Fluid Affinity Assessed from T1/T2 Ratio. Katika, Saidian, Prasad, + Fabricius (2017). Petrophysics Vol. 58, No. 2 (April 2017), pp. 126-140. DOI: none assigned (this + issue predates SPWLA DOI assignment). +src2017_10/article4_joint_inversion_nearwellbore -- Article 4: Imaging Near-Wellbore Petrophysical + Properties by Joint Inversion of Sonic, Resistivity, and Density Logging Data. Shetty, Liang, + Simoes, Canesin, Boyd, Zeroug, Sinha, Habashy, Domingues, Amorim, Abbots (2017). Petrophysics + Vol. 58, No. 5 (October 2017), pp. 501-516. DOI: none assigned (this issue predates SPWLA DOI + assignment). +src2017_12/article3_carbonate_pore_structure_sonic -- Article 3: Characterization of Pore Structure + Variation and Permeability Heterogeneity in Carbonate Rocks Using MICP and Sonic Logs: Puguang + Gas Field, China. Huang, Dou, Sun (2017). Petrophysics Vol. 58, No. 6 (December 2017), pp. + 576-591. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2018_10/article3_kerogen_log_geomechanics -- Article 3: Integrating Measured Kerogen Properties + With Log Analysis for Petrophysics and Geomechanics in Unconventional Resources. Craddock, Mosse, + Prioul, Miles, Loan, Pirie, Rylander, Lewis, Pomerantz (2018). DOI: 10.30632/PJV59N5-2018a2. +src2018_12/article3_poisson_ratio_functional_network -- Article 3: A Rigorous Data-Driven Approach + to Predict Poisson's Ratio of Carbonate Rocks Using a Functional Network. Tariq, Abdulraheem, + Mahmoud, Ahmed (2018). DOI: 10.30632/PJV59N6Y2018a2. Petrophysics Vol. 59 No. 6 (Dec 2018) — + Special Issue: Data-Driven Analytics in Logging and Petrophysics. +src2018_12/article7_hydraulic_fracture_optimization -- Article 7: Use of Data Analytics to Optimize + Hydraulic Fracture Locations Along Borehole. Gupta, Rai, Devegowda, Sondergeld (2018). DOI: + 10.30632/PJV59N6Y2018a6. Petrophysics Vol. 59 No. 6 (Dec 2018) — Special Issue: Data-Driven + Analytics in Logging and Petrophysics. +src2019_02/article5_composite_cement_well_integrity -- Article 5: Novel Composite Cement for + Improved Well Integrity Evaluation. Elshahawi, Huang, Pollock, Veedu (2019). DOI: + 10.30632/PJV60N1Y2019a4. Petrophysics Vol. 60 No. 1 (Feb 2019). +src2019_12/article2_ultrasonic_lwd_imaging -- Article 2: New 4.75-in. Ultrasonic LWD Technology + Provides High-Resolution Caliper and Imaging in Oil-Based and Water-Based Muds. Li, Lee, Coates, + Jin, Wong (2019). DOI: 10.30632/PJV60N6-2019a2. Petrophysics Vol. 60 No. 6 (Dec 2019). +src2020_04/article2_coupled_nmr_ultrasonic -- Article 2: A New Apparatus for Coupled Low-Field NMR + and Ultrasonic Measurements in Rocks at Reservoir Conditions. Connolly, Sarout, Dautriat, May, + Johns (2020). DOI: 10.30632/PJV61N2-2020a2. Petrophysics Vol. 61 No. 2 (Apr 2020). +src2020_06/article1_casedhole_horizontal_fe -- Article 1: Lessons Learned From Casedhole Formation + Evaluation Along Unconventional Horizontal Wells. Sullivan, Wang, Bolshakov, Song, Lazorek, + Tohidi, Seth (2020). DOI: 10.30632/PJV61N3-2020a1. Petrophysics Vol. 61 No. 3 (Jun 2020). +src2020_08/article3_thermochemical_stimulation -- Article 3: Improvement of Petrophysical + Properties of Tight Sandstone and Limestone Reservoirs Using Thermochemical Fluids. Mustafa, + Mahmoud, Abdulraheem, Tariq, Al-Nakhli (2020). DOI: 10.30632/PJV61N4-2020a3. Petrophysics Vol. 61 + No. 4 (Aug 2020). +src2020_10/article6_sonic_transit_drilling_nn -- Article 6: Prediction of Sonic Wave Transit Times + From Drilling Parameters While Horizontal Drilling in Carbonate Rocks Using Neural Networks. + Gowida, Elkatatny (2020). DOI: 10.30632/PJV61N5-2020a6. Petrophysics Vol. 61 No. 5 (Oct 2020). +src2021_02/article7_lwd_dual_ultrasonic_slowness -- Article 7: Revealing Hidden Information - High- + Resolution Logging-While-Drilling Slowness Measurements and Imaging Using Advanced Dual + Ultrasonic Technology. Blyth, Sakiyama, Hori, Yamamoto, Nakajima, Fahim Ud Din, Haecker, + Kittridge (2021). DOI: 10.30632/PJV62N1-2021a6. Petrophysics Vol. 62 No. 1 (Feb 2021). +src2021_04/article4_nonlinear_acoustics_mixing -- Article 4: Nonlinear Acoustics Applications for + Near-Wellbore Formation Evaluation. Skelt, TenCate, Guyer, Johnson, Larmat, Le Bas, Nihei, Vu + (2021). DOI: 10.30632/PJV62N2-2021a4. Petrophysics Vol. 62 No. 2 (Apr 2021). +src2021_06/article3 -- Article 3: Real-Time Prediction of Acoustic Velocities While Drilling + Vertical Complex Lithology Using AI Technique. Alsaihati, Elkatatny (2021). DOI: + 10.30632/PJV62N3-2021a2. Petrophysics Vol. 62 No. 3 (Jun 2021). +src2021_06/article4_ml_sonic_shear -- Article 4: Machine-Learning-Enabled Automatic Sonic Shear + Processing. Liang, Lei (2021). DOI: 10.30632/PJV62N3-2021a3. Petrophysics Vol. 62 No. 3 (Jun + 2021). +src2021_08/article7_volcanic_saturation_gassmann -- Article 7: Experimental Study on the Saturation + Model of Volcanic Rock Based on Fluid Distribution. Pan, Zhou, Guo, Si, Lin (2021). DOI: + 10.30632/PJV62N4-2021a6. Petrophysics Vol. 62 No. 4 (Aug 2021). +src2021_10/article7_3dprint_anisotropic_elastic -- Article 7: Effect of Fluids on the Elastic + Properties of 3D-Printed Anisotropic Rock Models. Dande, Stewart, Dyaur (2021). DOI: + 10.30632/PJV62N5-2021a7. Petrophysics Vol. 62 No. 5 (Oct 2021). +src2021_10/article9_perforation_fracture_morphology -- Article 9: Research of Near-Wellbore + Fracture Morphology, Formation Mechanism, and Propagation Law for Different Perforation Modes + During the Perforation Process. Wang, Li, Xu, Jia, Zhang (2021). DOI: 10.30632/PJV62N5-2021a9. + Petrophysics Vol. 62 No. 5 (Oct 2021). +src2021_12/article07_multistring_isolation_acoustic -- Article 7: Case Studies on Multistring + Isolation Evaluation in P&A Operations. Zhang, Mueller, Bryce, Brockway, Iskander (2021). DOI: + 10.30632/PJV62N6-2021a7. Petrophysics Vol. 62 No. 6 (Dec 2021). +src2022_02/article4_ultrasonic_creeping_shale -- Article 4: Ultrasonic Logging of Creeping Shale. + Diez, Johansen, Larsen (2022). DOI: 10.30632/PJV63N1-2022a4. Petrophysics Vol. 63 No. 1 (Feb + 2022). +src2022_04/article6_gas_hydrate_rock_physics -- Article 6: Rock Physics Modeling of Gas Hydrate + Reservoirs Through Integrated Core and Well-Log Data in NGHP-02 Area, KG Offshore Basin, India. + Kumar, Mishra, Chatterjee, Tiwari, Avadhani (2022). DOI: 10.30632/PJV63N2-2022a6. Petrophysics + Vol. 63 No. 2 (Apr 2022). +src2022_04/article7_digital_core_wellbore_stability -- Article 7: Application of Digital Core + Technology in Wellbore Stability Research. Zhou, Ye, Zhu, Cheng, Song, Wang, Cai (2022). DOI: + 10.30632/PJV63N2-2022a7. Petrophysics Vol. 63 No. 2 (Apr 2022). +src2022_08/article1_gas_condensate_fpg -- Article 1: Predicting In-Situ Physical Properties for Gas + Condensates From Fluid Pressure Gradients. Bryndzia, Kittridge (2022). DOI: + 10.30632/PJV63N4-2022a1. Petrophysics Vol. 63 No. 4 (Aug 2022). +src2022_12/article1_das_vsp_fwi -- Article 1: Full-Waveform Inversion of Fiber-Optic VSP Data From + Deviated Wells. Podgornova, Bettinelli, Liang, Le Calvez, Leaney, Perez, Soliman (2022). DOI: + 10.30632/PJV63N6-2022a1. Petrophysics Vol. 63 No. 6 (Dec 2022) — Best Papers of the 2022 SPWLA + Annual Symposium special issue. +src2023_02/article5_digital_core_poisson -- Article 5: Analysis of Influencing Factors of Poisson's + Ratio in Deep Shale Gas Reservoir Based on Digital Core Simulation. Liu, Wang, Lai, Wang, Zhang, + Zhang, Ou (2023). DOI: 10.30632/PJV64N1-2023a5. Petrophysics Vol. 64 No. 1 (Feb 2023). +src2023_10/article_02_desroches_stress_measurement -- Desroches, J., Peyret, E., Gisolf, A., + Wilcox, A., Di Giovanni, M., Schram de Jong, A., Sepehri, S., Garrard, R., and Giger, S. (2023). + "Stress Measurement Campaign in Scientific Deep Boreholes: Focus on Tools and Methods." + Petrophysics, 64(5), 621-639. DOI: 10.30632/PJV64N5-2023a2. +src2025_04/ultrasonic_pore_characterization -- Ultrasonic Microscopy Imaging of Carbonate Reservoir + Pore Structure. Based on: Chen et al., "New Methodology for Ultrasonic Microscopy Imaging of + Carbonate Reservoirs' Pore Structure", Petrophysics, Vol. 66, No. 2, April 2025, pp. 267–282. +src2025_10/a1_log_interpretation -- Article 1: Log Interpretation for Petrophysical and Elastic + Properties of Fine-Grained Sedimentary Rocks Authors: Ermis Proestakis and Ida Lykke Fabricius + Ref: Petrophysics, Vol. 66, No. 5 (October 2025), pp. 705-727. DOI: 10.30632/PJV66N5-2025a1. """ from __future__ import annotations @@ -44,6 +182,10 @@ def moduli_from_velocity(vp: ArrayLike, vs: ArrayLike, rho: ArrayLike) -> tuple[ ``G = rho*Vs**2``; ``K = rho*Vp**2 - 4/3*G``. Returns ``(K, G)`` in Pa (with SI inputs). The corpus writes the pair both ``(K, G)`` and ``(G, K)`` -- the order here is fixed as ``(K, G)``. + + Sources: src2017_12/article3_carbonate_pore_structure_sonic, + src2020_08/article3_thermochemical_stimulation, + src2021_10/article7_3dprint_anisotropic_elastic. """ vp_a = _arr(vp) vs_a = _arr(vs) @@ -57,6 +199,10 @@ def velocity_from_moduli(k: ArrayLike, g: ArrayLike, rho: ArrayLike) -> tuple[_F """P/S velocities from bulk/shear modulus and density -> ``(Vp, Vs)``. ``Vp = sqrt((K + 4/3*G)/rho)``; ``Vs = sqrt(G/rho)`` (m/s with SI inputs). + + Sources: src2017_10/article4_joint_inversion_nearwellbore, + src2017_12/article3_carbonate_pore_structure_sonic, + src2020_04/article2_coupled_nmr_ultrasonic. """ k_a = _arr(k) g_a = _arr(g) @@ -67,7 +213,12 @@ def velocity_from_moduli(k: ArrayLike, g: ArrayLike, rho: ArrayLike) -> tuple[_F def stiffness_from_velocity(rho: ArrayLike, v: ArrayLike) -> _Float: - """Stiffness coefficient ``C = rho*V**2`` (the P-wave modulus ``M`` for Vp).""" + """Stiffness coefficient ``C = rho*V**2`` (the P-wave modulus ``M`` for Vp). + + Sources: src2016_04/article5_acoustic_anisotropy_no_stoneley, + src2017_04/article4_t1t2_affinity_gassmann, src2020_08/article3_thermochemical_stimulation, + src2021_10/article7_3dprint_anisotropic_elastic, src2022_08/article1_gas_condensate_fpg. + """ return np.asarray(_arr(rho) * _arr(v) ** 2) @@ -75,6 +226,8 @@ def lame_from_velocity(vp: ArrayLike, vs: ArrayLike, rho: ArrayLike) -> tuple[_F """Lame parameters from velocities and density -> ``(lambda, mu)``. ``mu = rho*Vs**2``; ``lambda = rho*Vp**2 - 2*mu`` (Pa with SI inputs). + + Sources: src2021_04/article4_nonlinear_acoustics_mixing. """ vp_a = _arr(vp) vs_a = _arr(vs) @@ -115,6 +268,10 @@ def youngs_poisson_dynamic(vp: ArrayLike, vs: ArrayLike, rho: ArrayLike) -> tupl ``nu = (Vp**2 - 2*Vs**2)/(2*(Vp**2 - Vs**2))``; ``E = rho*Vs**2*(3*Vp**2 - 4*Vs**2)/(Vp**2 - Vs**2)`` (E in Pa with SI inputs). + + Sources: src2020_08/article3_thermochemical_stimulation, + src2020_10/article6_sonic_transit_drilling_nn, + src2021_10/article7_3dprint_anisotropic_elastic. """ vp2 = _arr(vp) ** 2 vs2 = _arr(vs) ** 2 @@ -125,28 +282,45 @@ def youngs_poisson_dynamic(vp: ArrayLike, vs: ArrayLike, rho: ArrayLike) -> tupl def youngs_from_kg(k: ArrayLike, g: ArrayLike) -> _Float: - """Young's modulus from bulk and shear modulus ``E = 9*K*G/(3*K + G)``.""" + """Young's modulus from bulk and shear modulus ``E = 9*K*G/(3*K + G)``. + + Sources: src2018_10/article3_kerogen_log_geomechanics, + src2022_04/article7_digital_core_wellbore_stability. + """ k_a = _arr(k) g_a = _arr(g) return np.asarray(9.0 * k_a * g_a / (3.0 * k_a + g_a)) def poisson_from_kg(k: ArrayLike, g: ArrayLike) -> _Float: - """Poisson's ratio from bulk and shear modulus ``nu = (3K - 2G)/(2*(3K + G))``.""" + """Poisson's ratio from bulk and shear modulus ``nu = (3K - 2G)/(2*(3K + G))``. + + Sources: src2018_10/article3_kerogen_log_geomechanics, + src2023_02/article5_digital_core_poisson. + """ k_a = _arr(k) g_a = _arr(g) return np.asarray((3.0 * k_a - 2.0 * g_a) / (2.0 * (3.0 * k_a + g_a))) def poisson_from_velocity(vp: ArrayLike, vs: ArrayLike) -> _Float: - """Poisson's ratio from P/S velocities ``(Vp**2 - 2*Vs**2)/(2*(Vp**2 - Vs**2))``.""" + """Poisson's ratio from P/S velocities ``(Vp**2 - 2*Vs**2)/(2*(Vp**2 - Vs**2))``. + + Sources: src2018_12/article3_poisson_ratio_functional_network, + src2020_08/article3_thermochemical_stimulation, + src2020_10/article6_sonic_transit_drilling_nn, + src2021_10/article7_3dprint_anisotropic_elastic. + """ vp2 = _arr(vp) ** 2 vs2 = _arr(vs) ** 2 return np.asarray((vp2 - 2.0 * vs2) / (2.0 * (vp2 - vs2))) def pwave_modulus(k: ArrayLike, g: ArrayLike) -> _Float: - """P-wave (constrained) modulus ``M = K + 4/3*G``.""" + """P-wave (constrained) modulus ``M = K + 4/3*G``. + + Sources: src2025_10/a1_log_interpretation. + """ return np.asarray(_arr(k) + 4.0 / 3.0 * _arr(g)) @@ -159,17 +333,28 @@ def voigt(f: ArrayLike, m: ArrayLike, *, axis: int = -1) -> _Float: """Voigt (arithmetic) bound ``sum(f_i*m_i)`` over the mixing axis. ``f`` volume fractions and ``m`` component moduli along ``axis``. + + Sources: src2014_02/article5_thermal_conductivity_velocity, + src2017_04/article4_t1t2_affinity_gassmann, + src2021_08/article7_volcanic_saturation_gassmann. """ return np.asarray(np.sum(_arr(f) * _arr(m), axis=axis)) def reuss(f: ArrayLike, m: ArrayLike, *, axis: int = -1) -> _Float: - """Reuss (harmonic) bound ``1/sum(f_i/m_i)`` over the mixing axis.""" + """Reuss (harmonic) bound ``1/sum(f_i/m_i)`` over the mixing axis. + + Sources: src2014_02/article5_thermal_conductivity_velocity, + src2017_04/article4_t1t2_affinity_gassmann. + """ return np.asarray(1.0 / np.sum(_arr(f) / _arr(m), axis=axis)) def voigt_reuss_hill(f: ArrayLike, m: ArrayLike, *, axis: int = -1) -> _Float: - """Voigt-Reuss-Hill average ``0.5*(Voigt + Reuss)``.""" + """Voigt-Reuss-Hill average ``0.5*(Voigt + Reuss)``. + + Sources: src2018_10/article3_kerogen_log_geomechanics. + """ return np.asarray(0.5 * (voigt(f, m, axis=axis) + reuss(f, m, axis=axis))) @@ -177,6 +362,9 @@ def wood_fluid_modulus(saturations: ArrayLike, moduli: ArrayLike, *, axis: int = """Wood's law effective fluid modulus (Reuss average over fluid phases). ``1/K_fl = sum(S_i/K_i)`` with saturations summing to one along ``axis``. + + Sources: src2017_10/article4_joint_inversion_nearwellbore, + src2021_08/article7_volcanic_saturation_gassmann. """ return reuss(saturations, moduli, axis=axis) @@ -187,6 +375,9 @@ def brie_fluid_modulus( """Brie et al. (1995) fluid-mixing modulus ``(K_liq - K_gas)*Sw**e + K_gas``. ``e`` is the Brie exponent (default 3.0); ``Sw`` is the liquid saturation. + + Sources: src2017_10/article4_joint_inversion_nearwellbore, + src2021_08/article7_volcanic_saturation_gassmann. """ sw_a = _arr(sw) return np.asarray((_arr(k_liquid) - _arr(k_gas)) * sw_a**e + _arr(k_gas)) @@ -200,6 +391,11 @@ def gassmann_ksat( ``K_sat = K_dry + (1 - K_dry/K_min)**2 / (phi/K_fl + (1 - phi)/K_min - K_dry/K_min**2)``. Keyword-only to defeat the ``k_dry``/``k_sat`` argument collision. + + Sources: src2017_04/article4_t1t2_affinity_gassmann, + src2021_08/article7_volcanic_saturation_gassmann, + src2021_10/article7_3dprint_anisotropic_elastic, + src2022_04/article6_gas_hydrate_rock_physics, src2025_10/a1_log_interpretation. """ kd = _arr(k_dry) km = _arr(k_mineral) @@ -237,6 +433,13 @@ def acoustic_impedance(rho: ArrayLike, v: ArrayLike, *, out: str = "rayl") -> _F """Acoustic impedance ``Z = rho*v``. ``out="rayl"`` returns SI Rayl (kg/m2/s); ``"mrayl"`` returns MRayl (Z/1e6). + + Sources: src2014_06/article1_bazhenov_rock_physics, + src2019_12/article2_ultrasonic_lwd_imaging, src2020_06/article1_casedhole_horizontal_fe, + src2021_02/article7_lwd_dual_ultrasonic_slowness, + src2021_10/article7_3dprint_anisotropic_elastic, + src2021_12/article07_multistring_isolation_acoustic, + src2025_04/ultrasonic_pore_characterization. """ z = _arr(rho) * _arr(v) if out == "rayl": @@ -250,6 +453,14 @@ def reflection_coefficient(z1: ArrayLike, z2: ArrayLike) -> _Float: """Normal-incidence reflection coefficient ``(Z2 - Z1)/(Z2 + Z1)``. ``z1`` is the incident-side impedance, ``z2`` the transmitted side. + + Sources: src2016_12/article5_ultrasonic_permeability_carbonate, + src2019_02/article5_composite_cement_well_integrity, + src2019_12/article2_ultrasonic_lwd_imaging, + src2021_02/article7_lwd_dual_ultrasonic_slowness, + src2021_12/article07_multistring_isolation_acoustic, + src2022_02/article4_ultrasonic_creeping_shale, src2022_12/article1_das_vsp_fwi, + src2025_04/ultrasonic_pore_characterization. """ z1_a = _arr(z1) z2_a = _arr(z2) @@ -257,7 +468,10 @@ def reflection_coefficient(z1: ArrayLike, z2: ArrayLike) -> _Float: def transmission_energy(z1: ArrayLike, z2: ArrayLike) -> _Float: - """Transmitted energy fraction ``1 - R**2`` at a normal-incidence interface.""" + """Transmitted energy fraction ``1 - R**2`` at a normal-incidence interface. + + Sources: src2021_12/article07_multistring_isolation_acoustic. + """ r = reflection_coefficient(z1, z2) return np.asarray(1.0 - r**2) @@ -291,19 +505,31 @@ def snell_angle(v1: ArrayLike, v2: ArrayLike, *, degrees: bool = True) -> _Float def thomsen_epsilon(c11: ArrayLike, c33: ArrayLike) -> _Float: - """Thomsen ``epsilon = (C11 - C33)/(2*C33)`` (P-wave anisotropy).""" + """Thomsen ``epsilon = (C11 - C33)/(2*C33)`` (P-wave anisotropy). + + Sources: src2016_04/article5_acoustic_anisotropy_no_stoneley, + src2021_10/article7_3dprint_anisotropic_elastic. + """ c33_a = _arr(c33) return np.asarray((_arr(c11) - c33_a) / (2.0 * c33_a)) def thomsen_gamma(c66: ArrayLike, c44: ArrayLike) -> _Float: - """Thomsen ``gamma = (C66 - C44)/(2*C44)`` (S-wave anisotropy).""" + """Thomsen ``gamma = (C66 - C44)/(2*C44)`` (S-wave anisotropy). + + Sources: src2015_10/article1_acoustic_anisotropy, + src2016_04/article5_acoustic_anisotropy_no_stoneley, src2021_06/article4_ml_sonic_shear, + src2021_10/article7_3dprint_anisotropic_elastic. + """ c44_a = _arr(c44) return np.asarray((_arr(c66) - c44_a) / (2.0 * c44_a)) def thomsen_delta(c13: ArrayLike, c33: ArrayLike, c44: ArrayLike) -> _Float: - """Thomsen ``delta = ((C13 + C44)**2 - (C33 - C44)**2)/(2*C33*(C33 - C44))``.""" + """Thomsen ``delta = ((C13 + C44)**2 - (C33 - C44)**2)/(2*C33*(C33 - C44))``. + + Sources: src2016_04/article5_acoustic_anisotropy_no_stoneley. + """ c33_a = _arr(c33) c44_a = _arr(c44) return np.asarray( @@ -312,22 +538,34 @@ def thomsen_delta(c13: ArrayLike, c33: ArrayLike, c44: ArrayLike) -> _Float: def annie_c13(c11: ArrayLike, c66: ArrayLike) -> _Float: - """ANNIE approximation ``C13 = C11 - 2*C66`` (assumes ``C13 = C12``).""" + """ANNIE approximation ``C13 = C11 - 2*C66`` (assumes ``C13 = C12``). + + Sources: src2016_12/article1_shale_fracturing_ml. + """ return np.asarray(_arr(c11) - 2.0 * _arr(c66)) def annie_c11(c33: ArrayLike, c44: ArrayLike, c66: ArrayLike) -> _Float: - """ANNIE approximation ``C11 = 2*(C66 - C44) + C33``.""" + """ANNIE approximation ``C11 = 2*(C66 - C44) + C33``. + + Sources: src2016_12/article1_shale_fracturing_ml. + """ return np.asarray(2.0 * (_arr(c66) - _arr(c44)) + _arr(c33)) def mannie_c13(c11: ArrayLike, c66: ArrayLike, *, k: float = 1.0) -> _Float: - """Modified-ANNIE ``C13 = k*(C11 - 2*C66)`` (``k=1`` recovers ANNIE).""" + """Modified-ANNIE ``C13 = k*(C11 - 2*C66)`` (``k=1`` recovers ANNIE). + + Sources: src2016_12/article1_shale_fracturing_ml. + """ return np.asarray(k * (_arr(c11) - 2.0 * _arr(c66))) def mannie_c11(c33: ArrayLike, c44: ArrayLike, c66: ArrayLike, *, kp: float = 1.0) -> _Float: - """Modified-ANNIE ``C11 = kp*2*(C66 - C44) + C33`` (``kp=1`` recovers ANNIE).""" + """Modified-ANNIE ``C11 = kp*2*(C66 - C44) + C33`` (``kp=1`` recovers ANNIE). + + Sources: src2016_12/article1_shale_fracturing_ml. + """ return np.asarray(kp * (2.0 * (_arr(c66) - _arr(c44))) + _arr(c33)) @@ -341,7 +579,11 @@ def mannie2_c66(c11: ArrayLike, c33: ArrayLike, c44: ArrayLike, *, k: float = 0. def shear_wave_splitting(v_fast: ArrayLike, v_slow: ArrayLike) -> _Float: - """Shear-wave splitting (anisotropy) ``(V_fast - V_slow)/V_fast``.""" + """Shear-wave splitting (anisotropy) ``(V_fast - V_slow)/V_fast``. + + Sources: src2014_06/article1_bazhenov_rock_physics, + src2016_12/article2_orthorhombic_geomechanics. + """ vf = _arr(v_fast) return np.asarray((vf - _arr(v_slow)) / vf) @@ -366,6 +608,8 @@ def vti_engineering_moduli( nu_v = c13/(c11 + c12) nu_h = (c12*c33 - c13**2)/(c11*c33 - c13**2) Gvh = c44, Ghh = c66 + + Sources: src2020_06/article1_casedhole_horizontal_fe. """ c11a = _arr(c11) c33a = _arr(c33) @@ -393,7 +637,10 @@ def vti_engineering_moduli( def biot_coefficient(k_dry: ArrayLike, k_mineral: ArrayLike) -> _Float: - """Biot-Willis effective-stress coefficient ``alpha = 1 - K_dry/K_mineral``.""" + """Biot-Willis effective-stress coefficient ``alpha = 1 - K_dry/K_mineral``. + + Sources: src2014_08/article6_siliceous_ooze_petrophysics, src2025_10/a1_log_interpretation. + """ return np.asarray(1.0 - _arr(k_dry) / _arr(k_mineral)) @@ -450,6 +697,10 @@ def min_horizontal_stress( and the strain terms it is the Thiercelin-Plumb poroelastic form (the corpus writes both under this name and as ``closure_stress``). ``e`` is Young's modulus in the same pressure unit as the stresses. + + Sources: src2016_04/article5_acoustic_anisotropy_no_stoneley, + src2016_10/article5_microfracturing_insitu_stress, + src2018_12/article7_hydraulic_fracture_optimization. """ nu_a = _arr(nu) pp_a = _arr(pp) @@ -466,17 +717,26 @@ def breakdown_pressure( """Hubbert-Willis breakdown pressure ``3*sh - sH - Pp + T0``. ``sh`` minimum and ``sH`` maximum horizontal stress; ``T0`` tensile strength. + + Sources: src2016_10/article5_microfracturing_insitu_stress, + src2021_10/article9_perforation_fracture_morphology. """ return np.asarray(3.0 * _arr(sh) - _arr(sH) - _arr(pp) + _arr(tensile_strength)) def reopening_pressure(sh: ArrayLike, sH: ArrayLike, pp: ArrayLike) -> _Float: - """Fracture reopening pressure ``3*sh - sH - Pp`` (breakdown with T0=0).""" + """Fracture reopening pressure ``3*sh - sH - Pp`` (breakdown with T0=0). + + Sources: src2016_10/article5_microfracturing_insitu_stress. + """ return np.asarray(3.0 * _arr(sh) - _arr(sH) - _arr(pp)) def shmax_from_reopening(pr: ArrayLike, sh: ArrayLike, pp: ArrayLike) -> _Float: - """Maximum horizontal stress from the reopening pressure ``sH = 3*sh - Pr - Pp``.""" + """Maximum horizontal stress from the reopening pressure ``sH = 3*sh - Pr - Pp``. + + Sources: src2016_10/article5_microfracturing_insitu_stress. + """ return np.asarray(3.0 * _arr(sh) - _arr(pr) - _arr(pp)) @@ -485,6 +745,8 @@ def kirsch_hoop_stress(sH: ArrayLike, sh: ArrayLike, pw: ArrayLike, theta_deg: A ``sigma_theta = (sH + sh) - 2*(sH - sh)*cos(2*theta) - Pw`` with ``theta`` measured from the ``sH`` azimuth (degrees). + + Sources: src2021_10/article9_perforation_fracture_morphology. """ th = np.radians(_arr(theta_deg)) sH_a = _arr(sH) @@ -507,6 +769,8 @@ def brittleness_rickman( ``e_range``/``nu_range`` are the normalisation endpoints (defaults are Rickman's GPa / dimensionless brackets); ``percent`` scales to 0-100. ``E`` must be given in the same units as ``e_range`` (GPa by default). + + Sources: src2018_12/article7_hydraulic_fracture_optimization. """ e_a = _arr(e) nu_a = _arr(nu) @@ -552,6 +816,9 @@ def overburden_stress(depth: ArrayLike, rho_bulk: ArrayLike, *, g: float = G_STA ``rho_bulk`` is the (average or per-sample) overburden bulk density and ``g`` defaults to standard gravity; the cumulative depth-column integration with a seawater layer stays in the caller (a field-unit corpus form). + + Sources: src2023_10/article_02_desroches_stress_measurement, + src2025_10/a1_log_interpretation. """ return np.asarray(_arr(rho_bulk) * g * _arr(depth)) diff --git a/petrolib/borehole_image.py b/petrolib/borehole_image.py index 3a92649..562d636 100644 --- a/petrolib/borehole_image.py +++ b/petrolib/borehole_image.py @@ -8,6 +8,33 @@ Azimuths and dips are in **degrees** at the interface (converted internally); images are indexed ``[depth, azimuth]`` (rows = depth, columns = azimuth). + +References +---------- +Complete citations for the source tags used in this module (SPWLA journal +*Petrophysics*): + +src2019_04/article4_image_segmentation_uncertainty -- Article 4: Uncertainty Quantification in + Image Segmentation for Image-Based Rock Physics in a Shaly Sandstone. Howard, Lin, Zhang (2019). + DOI: 10.30632/PJV60N2-2019a2. Petrophysics Vol. 60 No. 2 (Apr 2019). +src2020_10/article7_multiphysics_rock_classification -- Article 7: Integrated Multiphysics Workflow + for Automatic Rock Classification and Formation Evaluation Using Multiscale Image Analysis and + Conventional Well Logs. Gonzalez, Kanyan, Heidari, Lopez (2020). DOI: 10.30632/PJV61N5-2020a7. + Petrophysics Vol. 61 No. 5 (Oct 2020). +src2021_06/article6_geosteering_2d_structural -- Article 6: Maximizing Net Pay in Penta-Lateral + Well With Advanced Proactive Geosteering and 2D Structural Analysis Using Azimuthal Resistivity + Measurements. Antonov, Kushnir, Martakov, Pazos, Small, Tropin, Maraj, Itter, Nelson, Rabinovich + (2021). DOI: 10.30632/PJV62N3-2021a5. Petrophysics Vol. 62 No. 3 (Jun 2021). +src2021_10/article2_image_processing_petrophysics -- Article 2: Enhanced Learning of Fundamental + Petrophysical Concepts Through Image Processing and 3D Printing. Alyafei, Al Musleh, Bautista, + Idris, Seers (2021). DOI: 10.30632/PJV62N5-2021a2. Petrophysics Vol. 62 No. 5 (Oct 2021). +src2021_12/article04_borehole_image_cnn_sedimentary -- Article 4: Deep-Learning-Based Automated + Sedimentary Geometry Characterization From Borehole Images. Lefranc, Bayraktar, Kristensen, + Driss, Le Nir, Marza, Kherroubi (2021). DOI: 10.30632/PJV62N6-2021a4. Petrophysics Vol. 62 No. 6 + (Dec 2021). +src2025_04/ultrasonic_pore_characterization -- Ultrasonic Microscopy Imaging of Carbonate Reservoir + Pore Structure. Based on: Chen et al., "New Methodology for Ultrasonic Microscopy Imaging of + Carbonate Reservoirs' Pore Structure", Petrophysics, Vol. 66, No. 2, April 2025, pp. 267–282. """ from __future__ import annotations @@ -37,6 +64,8 @@ def bed_sinusoid( ``z(phi) = z0 - radius*tan(dip)*cos(phi - dip_azimuth)`` -- a sinusoid of amplitude ``radius*tan(dip)`` whose deepest point is at the dip azimuth. All angles in degrees. + + Sources: src2021_12/article04_borehole_image_cnn_sedimentary. """ phi = np.radians(_arr(azimuth_deg)) a = np.radians(dip_azimuth_deg) @@ -73,7 +102,10 @@ def dip_from_amplitude(amplitude: float, radius: float, *, sample_spacing: float def apparent_dip(true_dip_deg: float, section_azimuth_deg: float) -> float: - """Apparent dip at section angle ``beta`` to true dip: ``tan(app)=tan(true)cos(beta)`` (deg).""" + """Apparent dip at section angle ``beta`` to true dip: ``tan(app)=tan(true)cos(beta)`` (deg). + + Sources: src2021_06/article6_geosteering_2d_structural. + """ return float( np.degrees( np.arctan(np.tan(np.radians(true_dip_deg)) * np.cos(np.radians(section_azimuth_deg))) @@ -87,6 +119,8 @@ def fit_plane(points_enz: ArrayLike) -> tuple[float, float]: The plane normal is the smallest-singular-value direction of the centred points; ``dip = arccos(|n_z|)`` and ``dip_azimuth = atan2(n_E, n_N) mod 360`` (clockwise from North). + + Sources: src2021_06/article6_geosteering_2d_structural. """ p = _arr(points_enz) centroid = p.mean(axis=0) @@ -108,6 +142,8 @@ def otsu_threshold(image: ArrayLike, *, bins: int = 256) -> float: ``sigma_b^2(t) = (mu_T*omega - mu)^2 / [omega(1-omega)]`` over the histogram of ``image`` (``bins`` bins spanning ``[min, max]``) and returns the value at the optimal bin centre. + + Sources: src2019_04/article4_image_segmentation_uncertainty. """ img = _arr(image).ravel() hist, edges = np.histogram(img, bins=bins, range=(float(img.min()), float(img.max()))) @@ -128,6 +164,8 @@ def class_fractions(image: ArrayLike, thresholds: ArrayLike) -> _Float: For ``thresholds = [t0, t1, ...]`` returns ``[mean(img=t_last)]`` -- e.g. pore / clay / grain from two thresholds (dark = pore convention). + + Sources: src2019_04/article4_image_segmentation_uncertainty. """ img = _arr(image).ravel() fracs = [] @@ -140,14 +178,20 @@ def class_fractions(image: ArrayLike, thresholds: ArrayLike) -> _Float: def phase_saturation(phase: ArrayLike, pore: ArrayLike) -> float: - """Saturation of a phase within the pore space: ``|phase & pore| / |pore|``.""" + """Saturation of a phase within the pore space: ``|phase & pore| / |pore|``. + + Sources: src2021_10/article2_image_processing_petrophysics. + """ ph = np.asarray(phase) po = np.asarray(pore) return float(np.logical_and(ph, po).sum()) / float(po.sum()) def porosity_from_mask(pore: ArrayLike) -> float: - """Porosity as the fraction of voxels flagged pore: ``pore.sum()/pore.size``.""" + """Porosity as the fraction of voxels flagged pore: ``pore.sum()/pore.size``. + + Sources: src2019_04/article4_image_segmentation_uncertainty. + """ m = np.asarray(pore) return float(m.sum()) / float(m.size) @@ -163,6 +207,8 @@ def glcm( Quantises ``image`` to ``levels`` grey levels by min-max scaling, then counts co-occurrences at ``offset = (drow, dcol)``. ``symmetric=True`` counts both directions; the result is normalised to sum to one. + + Sources: src2020_10/article7_multiphysics_rock_classification. """ img = _arr(image) rng = img.max() - img.min() @@ -181,7 +227,10 @@ def glcm( def glcm_features(p: ArrayLike) -> dict[str, float]: - """Haralick contrast / energy / correlation of a normalised GLCM ``p``.""" + """Haralick contrast / energy / correlation of a normalised GLCM ``p``. + + Sources: src2020_10/article7_multiphysics_rock_classification. + """ p_arr = _arr(p) n = p_arr.shape[0] i, j = np.meshgrid(np.arange(n), np.arange(n), indexing="ij") @@ -202,6 +251,8 @@ def sobel_gradient(image: ArrayLike) -> tuple[_Float, _Float, _Float]: ``gx`` is the horizontal (column) derivative, ``gy`` the vertical (row) derivative; ``magnitude = sqrt(gx^2 + gy^2)``. Interior pixels only; the one-pixel border stays zero. + + Sources: src2025_04/ultrasonic_pore_characterization. """ img = _arr(image) kx = np.array([[-1.0, 0.0, 1.0], [-2.0, 0.0, 2.0], [-1.0, 0.0, 1.0]]) diff --git a/petrolib/capillary_pressure.py b/petrolib/capillary_pressure.py index 1c024b4..ca323c9 100644 --- a/petrolib/capillary_pressure.py +++ b/petrolib/capillary_pressure.py @@ -27,6 +27,101 @@ Units: SI throughout — Pa, N/m, m, kg/m3, Pa*s, rad/s; ``theta_deg`` in degrees. The one deliberate exception is :func:`buoyancy_pc_gradient`, the oilfield psi/ft form, whose 0.433 psi/ft/SG gradient is a visible default. + +References +---------- +Complete citations for the source tags used in this module (SPWLA journal +*Petrophysics*): + +src2014_02/article2 -- Article 2: Capillary Pressure and Resistivity Index Measurements in a Mixed- + Wet Carbonate Reservoir Moustafa R. Dernaika, Mohamed S. Efnik, Safouh Koronfol, Svein M. + Skjaeveland, Maisoon M. Al Mansoori, Hafez Hafez, Mohammed Z. Kalam (2014). Petrophysics Vol. 55, + No. 1 (February 2014), pp. 24-30. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2015_02/article4 -- Article 4: Petrophysical Characterization of the Pore Space in Permian + Wolfcamp Rocks. Rafatian, Capsan (2015). Petrophysics Vol. 56, No. 1 (February 2015), pp. 45-57. + DOI: none assigned (this issue predates SPWLA DOI assignment). +src2016_02/article1 -- Article 1: The Impact of Reservoir Conditions and Rock Heterogeneity on + CO2-Brine Multiphase Flow in Permeable Sandstone. Krevor, Reynolds, Al-Menhali, Niu (2016). + Petrophysics Vol. 57, No. 1 (February 2016), pp. 12-18. DOI: none assigned (this issue predates + SPWLA DOI assignment). +src2016_06/article1 -- Article 1: Heterogeneous Carbonate Reservoirs: Ensuring Consistency of + Subsurface Models by Maximizing the use of Saturation-Height Models and Dynamic Data. Hulea, + Frese, Ramaswami (2016). Petrophysics Vol. 57, No. 3 (June 2016), pp. 223-232. DOI: none assigned + (this issue predates SPWLA DOI assignment). +src2016_10 -- Petrophysics Vol. 57 No. 5 (Oct 2016) (issue-level reference). +src2016_10/article2 -- Article 2: How Pore-Scale Attributes May Be Used to Derive Robust Drainage + and Imbibition Water-Saturation Models in Complex Tight-Gas Reservoirs. Merletti, Gramin, + Salunke, Hamman, Spain, Shabro, Armitage, Torres-Verdin, Salter, Dacy (2016). Petrophysics Vol. + 57, No. 5 (October 2016), pp. 447-464. DOI: none assigned (this issue predates SPWLA DOI + assignment). +src2017_02 -- Petrophysics Vol. 58 No. 1 (Feb 2017) (issue-level reference). +src2017_08/article3 -- Article 3: An Analytical Model for Analysis of Capillary Pressure + Measurements by Centrifuge. Andersen, Skjaeveland, Standnes (2017). Petrophysics Vol. 58, No. 4 + (August 2017), pp. 366-375. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2018_02 -- Petrophysics Vol. 59 No. 1 (Feb 2018) (issue-level reference). +src2018_06/article8 -- Article 8: Saturation-Height Modeling: Assessing Capillary Pressure Stress + Corrections. Hulea (2018). DOI: 10.30632/PJV59N3-2018a7 (inferred - see note). Petrophysics Vol. + 59 No. 3 (Jun 2018). +src2018_06/article8_saturation_height_stress_correction -- Article 8: Saturation-Height Modeling: + Assessing Capillary Pressure Stress Corrections. Hulea (2018). DOI: 10.30632/PJV59N3-2018a7 + (inferred - see note). Petrophysics Vol. 59 No. 3 (Jun 2018). +src2018_08/article1 -- Article 1 (Tutorial): Capillary Pressure Tutorial Part 1 - It's a Jungle in + Here. Thomas (2018). DOI: 10.30632/PJV59V4-2018t1. Petrophysics Vol. 59 No. 4 (Aug 2018) - + Special Issue on Flow Diagnostics. +src2018_10 -- Petrophysics Vol. 59 No. 5 (Oct 2018) - "Best of 2018 SPWLA Symposium" issue (issue- + level reference). +src2018_10/article1 -- Article 1 (Tutorial): Capillary Pressure Tutorial Part 2 - The Path Out of + the Jungle. Thomas (2018). DOI: 10.30632/PJV59N5-2018t1. Petrophysics Vol. 59 No. 5 (Oct 2018) - + "Best of 2018 SPWLA Symposium" issue. +src2018_10/article1_capillary_pressure_tutorial_part2 -- Article 1 (Tutorial): Capillary Pressure + Tutorial Part 2 - The Path Out of the Jungle. Thomas (2018). DOI: 10.30632/PJV59N5-2018t1. + Petrophysics Vol. 59 No. 5 (Oct 2018) - "Best of 2018 SPWLA Symposium" issue. +src2018_12 -- Petrophysics Vol. 59 No. 6 (Dec 2018) — Special Issue: Data-Driven Analytics in + Logging and Petrophysics (issue-level reference). +src2018_12/article1_capillary_pressure_tutorial_part3 -- Article 1 (Tutorial): Capillary Pressure + Tutorial Part 3 - The Jungle Gives Us Many Things. Murphy (2018). DOI: 10.30632/PJV59N6Y2018t1. + Petrophysics Vol. 59 No. 6 (Dec 2018) — Special Issue: Data-Driven Analytics in Logging and + Petrophysics. +src2019_06/article8 -- Article 8: Perched Water Contacts: Understanding Fundamental Controls. Hulea + (2019). DOI: 10.30632/PJV60N3-2019a7. Petrophysics Vol. 60 No. 3 (Jun 2019). +src2019_06/article8_perched_water_contacts -- Article 8: Perched Water Contacts: Understanding + Fundamental Controls. Hulea (2019). DOI: 10.30632/PJV60N3-2019a7. Petrophysics Vol. 60 No. 3 (Jun + 2019). +src2020_04 -- Petrophysics Vol. 61 No. 2 (Apr 2020) (issue-level reference). +src2020_04/article7 -- Article 7: Effect of Injection Pressure on the Imbibition Relative + Permeability and Capillary Pressure Curves of Shale Gas Matrix. Al-Ameri, Mazeel (2020). DOI: + 10.30632/PJV61N2-2020a7. Petrophysics Vol. 61 No. 2 (Apr 2020). +src2020_04/article8 -- Article 8: Spontaneous Gas-Water Imbibition in Mixed-Wet Pores. Wang, He, + Xiao, Wang, Ma (2020). DOI: 10.30632/PJV61N2-2020a8. Petrophysics Vol. 61 No. 2 (Apr 2020). +src2020_06 -- Petrophysics Vol. 61 No. 3 (Jun 2020) (issue-level reference). +src2020_08 -- Petrophysics Vol. 61 No. 4 (Aug 2020) (issue-level reference). +src2021_04 -- Petrophysics Vol. 62 No. 2 (Apr 2021) (issue-level reference). +src2021_04/article3 -- Article 3: Free or Bound? Thomeer and NMR Porosity Partitioning in Carbonate + Reservoirs, Alta Discovery, Southwestern Barents Sea. Gianotten, Rameil, Foyn, Kollien, Marre, + Looyestijn, Zhang, Hebing (2021). DOI: 10.30632/PJV62N2-2021a3. Petrophysics Vol. 62 No. 2 (Apr + 2021). +src2021_08 -- Petrophysics Vol. 62 No. 4 (Aug 2021) (issue-level reference). +src2021_08/article1 -- Article 1: Tutorial - Petrophysics of Thinly Bedded Formations. Aldred + (2021). DOI: 10.30632/PJV62N4-2021t1. +src2022_10 -- Petrophysics Vol. 63 No. 5 (Oct 2022) (issue-level reference). +src2022_10/article2 -- Article 2: Empirical Relation for Capillary Pressure in Shale. Alipour K., + Kasha, Sakhaee-Pour, Sadooni, Al-Kuwari (2022). DOI: 10.30632/PJV63N5-2022a2. Petrophysics Vol. + 63 No. 5 (Oct 2022). +src2023_06 -- Petrophysics Vol. 64 No. 3 (June 2023) — Best Papers of the 2022 SCA International + Symposium (issue-level reference). +src2023_08 -- Petrophysics Vol. 64 No. 4 (Aug 2023) (issue-level reference). +src2023_10 -- Petrophysics Vol. 64 No. 5 (Oct 2023) — Energy Transition Special Issue (issue-level + reference). +src2023_10/article_01_laronga_ccs_evaluation -- Laronga, R., Borchardt, E., Hill, B., Velez, E., + Klemin, D., Haddad, S., Haddad, E., Chadwick, C., Mahmoodaghdam, E., and Hamichi, F. (2023). + "Integrated Formation Evaluation for Site-Specific Evaluation, Optimization, and Permitting of + Carbon Storage Projects." Petrophysics, 64(5), 580-620. DOI: 10.30632/PJV64N5-2023a1. +src2024_12 -- Petrophysics Vol. 65 No. 6 (Dec 2024) (issue-level reference). +src2025_02 -- Petrophysics Vol. 66 No. 1 (Feb 2025) (issue-level reference). +src2025_12 -- Petrophysics Vol. 66 No. 6 (Dec 2025) — Best Papers of the 2024 SCA International + Symposium (issue-level reference). +src2025_12/nanopore_adsorption -- Wettability Effect on Adsorption and Capillary Condensation in + Nanopores. Petrophysics, 66(6), 1061–1071. DOI: 10.30632/PJV66N6-2025a10. """ from __future__ import annotations @@ -269,7 +364,13 @@ def buoyancy_pc(height: ArrayLike, *, delta_rho: ArrayLike, g: float = G_STD) -> def height_above_fwl(pc: ArrayLike, *, delta_rho: ArrayLike, g: float = G_STD) -> _Float: - """Height above the free-water level from Pc: inverse of :func:`buoyancy_pc`.""" + """Height above the free-water level from Pc: inverse of :func:`buoyancy_pc`. + + Sources: src2018_06/article8_saturation_height_stress_correction, + src2018_10/article1_capillary_pressure_tutorial_part2, + src2018_12/article1_capillary_pressure_tutorial_part3, + src2019_06/article8_perched_water_contacts, src2023_10/article_01_laronga_ccs_evaluation. + """ pc_arr = np.asarray(pc, np.float64) drho = np.asarray(delta_rho, np.float64) return np.asarray(pc_arr / (drho * g)) diff --git a/petrolib/constants.py b/petrolib/constants.py index ab4e454..e014b5f 100644 --- a/petrolib/constants.py +++ b/petrolib/constants.py @@ -13,6 +13,15 @@ Sources: repeated definitions across src2014_02 … src2026_06; see LIBRARY_MERGE_PLAN.md section 9 for the GAMMA_H hazard note. + +References +---------- +Complete citations for the source tags used in this module (SPWLA journal +*Petrophysics*): + +src2014_02 -- Petrophysics Vol. 55 No. 1 (Feb 2014) (issue-level reference). +src2026_06 -- Petrophysics Vol. 67 No. 3 (June 2026) — "Best Petrophysics Papers From MEOS GEO + 2025" (issue-level reference). """ from __future__ import annotations diff --git a/petrolib/data_qc_io/clean.py b/petrolib/data_qc_io/clean.py index 40da113..8a5a59a 100644 --- a/petrolib/data_qc_io/clean.py +++ b/petrolib/data_qc_io/clean.py @@ -7,6 +7,43 @@ src2018_12/article11 (gap imputation, IQR), src2024_08/magnetic_permeability (MAD despike), src2019_02/article4 (closure), src2023_08/article3 (renormalize), src2016_02/article3 & src2017_10/article5 (discrepancy). + +References +---------- +Complete citations for the source tags used in this module (SPWLA journal +*Petrophysics*): + +src2014_10/article2 -- Article 2: Application and Quality Control of Core Data for the Development + and Validation of Elemental Spectroscopy Log Interpretation Susan Herron, Michael Herron, Iain + Pirie, Pablo Saldungaray, Paul Craddock, Alyssa Charsky, Marina Polyakov, Frank Shray, Ting Li + (2014). Petrophysics Vol. 55, No. 5 (October 2014), pp. 392-414. DOI: none assigned (this issue + predates SPWLA DOI assignment). +src2016_02/article3 -- Article 3: Low-Permeability Measurements: Insights. Profice, Hamon, Nicot + (2016). Petrophysics Vol. 57, No. 1 (February 2016), pp. 30-40. DOI: none assigned (this issue + predates SPWLA DOI assignment). +src2017_10/article5 -- Article 5: Lessons Learned in Permian Core Analysis: Comparison Between + Retort, GRI, and Routine Methodologies. Blount, Croft, Driskill, Tepper (2017). Petrophysics Vol. + 58, No. 5 (October 2017), pp. 517-527. DOI: none assigned (this issue predates SPWLA DOI + assignment). +src2018_12/article11 -- Article 11: Data Preconditioning for Predictive and Interpretive + Algorithms: Importance in Data-Driven Analytics and Methods for Application. Frost, Quinn (2018). + DOI: 10.30632/PJV59N6Y2018a10. Petrophysics Vol. 59 No. 6 (Dec 2018) — Special Issue: Data-Driven + Analytics in Logging and Petrophysics. +src2019_02/article4 -- Article 4: Maintaining and Reconstructing In-Situ Saturations: A Comparison + Between Whole Core, Sidewall Core, and Pressurized Sidewall Core in the Permian Basin. Blount, + McMullen, Durand, Driskill (2019). DOI: 10.30632/PJV60N1Y2019a3. Petrophysics Vol. 60 No. 1 (Feb + 2019). +src2021_12/article01 -- Article 1: Data Quality Considerations for Petrophysical Machine-Learning + Models. McDonald (2021). DOI: 10.30632/PJV62N6-2021a1. Petrophysics Vol. 62 No. 6 (Dec 2021). +src2023_08/article3 -- Jácomo, M.H., Hartmann, G.A., Rebelo, T.B., Mattos, N.H., Batezelli, A., + Leite, E.P. (2023). "Mineralogical Modeling and Petrophysical Properties of the Barra Velha + Formation, Santos Basin, Brazil", Petrophysics, Vol. 64, No. 4, pp. 518-543. DOI: + 10.30632/PJV64N4-2023a3. +src2024_08/magnetic_permeability -- Applying Magnetic Susceptibility to Estimate Permeability From + Drill Cuttings. Based on: Banks, J.Y., Tugwell, A.G., and Potter, D.K. (2024), "Applying Magnetic + Susceptibility to Estimate Permeability From Drill Cuttings: A Case Study Constraining + Uncertainty in the Culzean Triassic Reservoir," Petrophysics, 65(4), pp. 604-623. DOI: + 10.30632/PJV65N4-2024a13. """ from __future__ import annotations diff --git a/petrolib/data_qc_io/filt.py b/petrolib/data_qc_io/filt.py index 8d3dd6f..ef6b9f8 100644 --- a/petrolib/data_qc_io/filt.py +++ b/petrolib/data_qc_io/filt.py @@ -6,6 +6,43 @@ smoother and the feature stack edge-pad (``np.pad(mode='edge')``, i.e. scipy's ``'nearest'``); moving statistics shrink the window at the edges. All spreads are population (``ddof=0``). + +References +---------- +Complete citations for the source tags used in this module (SPWLA journal +*Petrophysics*): + +src2020_10/article3 -- Article 3: Automatic Detection of Anomalous Density Measurements due to + Wellbore Cave-in. Sen, Ong, Kainkaryam, Sharma (2020). DOI: 10.30632/PJV61N5-2020a3. Petrophysics + Vol. 61 No. 5 (Oct 2020). +src2023_04/article10 -- Article 10: Machine-Learning-Based Deconvolution Method Provides High- + Resolution Fast Inversion of Induction Log Data. Hagiwara (2023). DOI: 10.30632/PJV64N2-2023a10. + Petrophysics Vol. 64 No. 2 (Apr 2023) — SPWLA AI/ML Special Issue. +src2023_06/article9 -- Aerens, P., Torres-Verdin, C., Espinoza, N. "Experimental Time-Lapse + Visualization of Mud-Filtrate Invasion and Mudcake Deposition Using X-Ray Radiography" + Petrophysics, Vol. 64, No. 3 (June 2023), pp. 448-461 DOI: 10.30632/PJV64N3-2023a9. +src2023_08/article5 -- Merletti, G., Rabinovich, M., Al Hajri, S., Dawson, W., Farmer, R., Ambia, + J., Torres-Verdín, C. (2023). "New Iterative Resistivity Modeling Workflow Reduces Uncertainty in + the Assessment of Water Saturation in Deeply Invaded Reservoirs", Petrophysics, Vol. 64, No. 4, + pp. 555-567. DOI: 10.30632/PJV64N4-2023a5. +src2023_10/article_03 -- Okwoli, E. and Potter, D. K. (2023). "Probe Screening Techniques for + Rapid, High-Resolution Core Analysis and Their Potential Usefulness for Energy Transition + Applications." Petrophysics, 64(5), 640-655. DOI: 10.30632/PJV64N5-2023a3. +src2023_10/article_09 -- Bennis, M. and Torres-Verdin, C. (2023). "Numerical Simulation of Well + Logs Based on Core Measurements: An Effective Method for Data Quality Control and Improved + Petrophysical Interpretation." Petrophysics, 64(5), 753-772. DOI: 10.30632/PJV64N5-2023a9. +src2024_06/article2 -- Strobel, J. (2024). "Petrophysical Analyses for Supporting the Search for a + Claystone-Hosted Nuclear Repository." Petrophysics 65(3), 302-316. DOI: 10.30632/PJV65N3-2024a2. +src2024_10/ml_permeability -- Automatic Permeability Estimation: ML Methods vs Conventional Models. + Based on: Raheem et al. (2024), "Best Practices in Automatic Permeability Estimation: Machine- + Learning Methods vs. Conventional Petrophysical Models", Petrophysics, Vol. 65, No. 5, pp. + 789-812. +src2024_10/thin_bed_nmr -- Thin-Bed NMR Response Characterisation in Horizontal Wells. Based on: + Ramadan et al. (2024), "Characterizing Thin-Bed Responses in Horizontal Wells Using LWD NMR + Tools: Insights From a Water Tank Experiment", Petrophysics, Vol. 65, No. 5, pp. 765-771. +src2026_04/a04 -- Liu, Z., Zhang, X., Fan, Q., Zhou, L., Zhang, Y., Zhao, Z., and Zhang, Z. (2026). + Intelligent Sensors and Algorithms for Diagnosing Downhole Operating Conditions of Wireline + Logging Instruments. Petrophysics, 67(2), 295–317. DOI: 10.30632/PJV67N2-2026a4. """ from __future__ import annotations diff --git a/petrolib/data_qc_io/io.py b/petrolib/data_qc_io/io.py index 3e1d923..284e23e 100644 --- a/petrolib/data_qc_io/io.py +++ b/petrolib/data_qc_io/io.py @@ -5,6 +5,15 @@ axis labels, covering simple 1-D logs through multi-dimensional measurements such as ultradeep azimuthal resistivity. Source: src2023_12/ bradley_wellbore_format.py (Petrophysics 64(6):823-836). + +References +---------- +Complete citations for the source tags used in this module (SPWLA journal +*Petrophysics*): + +src2023_12/bradley_wellbore_format -- Bradley et al. (2023), Petrophysics 64(6): 823-836. A + proposed universal format for storing/distributing wellbore data, capable of representing simple + 1D logs and complex multi-dimensional measurements (e.g. ultradeep azimuthal resistivity). """ from __future__ import annotations @@ -23,6 +32,8 @@ class WellboreData: ``channels`` maps name -> ``{"data", "units", "axes", "shape"}``. Round-trip via ``to_json``/``from_json`` (or ``to_dict``/``from_dict``); ``shape`` is recomputed on reload. + + Sources: src2023_12/bradley_wellbore_format. """ def __init__(self, well_name: str, uwi: str | None = None) -> None: diff --git a/petrolib/data_qc_io/scale.py b/petrolib/data_qc_io/scale.py index 7dfe7e7..07b60b7 100644 --- a/petrolib/data_qc_io/scale.py +++ b/petrolib/data_qc_io/scale.py @@ -4,6 +4,21 @@ already canon in :mod:`petrolib.ml_stats` (``zscore``, ``minmax``, ``affine_rescale``). Population std (``ddof=0``) throughout, matching every article copy. + +References +---------- +Complete citations for the source tags used in this module (SPWLA journal +*Petrophysics*): + +src2015_04/article4 -- Article 4: Microresistivity Curve Extraction from Borehole Microimager Data. + Roslin (2015). Petrophysics Vol. 56, No. 2 (April 2015), pp. 140-146. DOI: none assigned (this + issue predates SPWLA DOI assignment). +src2016_12/article6 -- Article 6 (Technical Note): Normalizing Gamma-Ray Logs Acquired from a + Mixture of Vertical and Horizontal Wells in the Haynesville Shale. Xu, Bayer, Wunderle, Bansal + (2016). Petrophysics Vol. 57, No. 6 (December 2016), pp. 638-643. DOI: none assigned (this issue + predates SPWLA DOI assignment). +src2021_12/article01 -- Article 1: Data Quality Considerations for Petrophysical Machine-Learning + Models. McDonald (2021). DOI: 10.30632/PJV62N6-2021a1. Petrophysics Vol. 62 No. 6 (Dec 2021). """ from __future__ import annotations diff --git a/petrolib/data_qc_io/signal.py b/petrolib/data_qc_io/signal.py index 3d01dab..3785a71 100644 --- a/petrolib/data_qc_io/signal.py +++ b/petrolib/data_qc_io/signal.py @@ -2,6 +2,29 @@ SNR is the power ratio ``10*log10(P_signal/P_noise)``; stacking of ``n`` repeats improves amplitude SNR by ``sqrt(n)``. + +References +---------- +Complete citations for the source tags used in this module (SPWLA journal +*Petrophysics*): + +src2021_04/article5 -- Article 5: An Integrated Petrophysical Workflow for Fluid Characterization + and Contacts Identification Using NMR Continuous and Stationary Measurements in a High-Porosity + Sandstone Formation, Offshore Norway. Kozlowski, Chakraborty, Jambunathan, Lowrey, Balliet, + Engelman, Anensen, Kotwicki, Johansen (2021). DOI: 10.30632/PJV62N2-2021a5. Petrophysics Vol. 62 + No. 2 (Apr 2021). +src2021_12/article01 -- Article 1: Data Quality Considerations for Petrophysical Machine-Learning + Models. McDonald (2021). DOI: 10.30632/PJV62N6-2021a1. Petrophysics Vol. 62 No. 6 (Dec 2021). +src2025_08/anomaly_detection_vmd -- Module 8: Automated Anomaly Detection via Signal Mode + Decomposition Implements ideas from: Wang et al., "Automated Anomaly Detection of Multimetallic + Tubulars in Well Integrity Logs Using Signal Mode Decomposition and Physics-Informed Decision + Making," Petrophysics, vol. 66, no. 4, pp. 647–661, August 2025. +src2025_08/fiber_optics_sensing -- Module 2: Fiber-Optic Sensing for Well Integrity Diagnosis + Implements ideas from: Bazaid et al., "Pioneering Well Logging: The Role of Fiber Optics in + Modern Monitoring for Well Integrity Diagnosis," Petrophysics, vol. 66, no. 4, pp. 555–565, + August 2025. +src2025_12/carbon13_mr -- ¹³C Magnetic Resonance Relaxation-Time Wettability Characterisation. + Petrophysics, 66(6), 1073–1089. DOI: 10.30632/PJV66N6-2025a11. """ from __future__ import annotations diff --git a/petrolib/data_qc_io/synth.py b/petrolib/data_qc_io/synth.py index 33d993f..8f24350 100644 --- a/petrolib/data_qc_io/synth.py +++ b/petrolib/data_qc_io/synth.py @@ -4,6 +4,40 @@ Generators are deterministic by default (``rng=None`` seeds ``default_rng`` with the source article's seed) so examples and tests reproduce; pass a seed or ``np.random.Generator`` to vary. + +References +---------- +Complete citations for the source tags used in this module (SPWLA journal +*Petrophysics*): + +src2022_02/article2 -- Article 2: Automated Well-Log Depth Matching - 1D Convolutional Neural + Networks vs. Classic Cross Correlation. Torres Caceres, Duffaut, Yazidi, Westad, Johansen (2022). + DOI: 10.30632/PJV63N1-2022a2. Petrophysics Vol. 63 No. 1 (Feb 2022). +src2022_06/article1 -- Article 1: Integrated Reservoir Characterization Using Unsupervised Learning + on Nuclear Magnetic Resonance (NMR) T1-T2 Logs. Jiang, Bonnie, Correa, Krueger, Kelly, Wasson + (2022). DOI: 10.30632/PJV63N3-2022a1. Petrophysics Vol. 63 No. 3 (Jun 2022) — NMR SIG Special + Issue. +src2022_06/article9 -- Article 9: NMR-Based Wettability Index for Unconventional Rocks. Dick, + Veselinovic, Bonnie, Kelly (2022). DOI: 10.30632/PJV63N3-2022a9. Petrophysics Vol. 63 No. 3 (Jun + 2022) — NMR SIG Special Issue. +src2022_08/article5 -- Article 5: Log Facies Analysis and Reservoir Properties of Basement Granitic + Rocks in the Pearl River Mouth Basin, South China Sea. Hua, Yang, Xu, Lei, Zhong (2022). DOI: + 10.30632/PJV63N4-2022a5. Petrophysics Vol. 63 No. 4 (Aug 2022). +src2022_12/article7 -- Article 7: Using Digital Rock Physics to Evaluate Novel Percussion Core + Quality. Lakshtanov, Zapata, Saucier, Cook, Eve, Lancaster, Lane, Gettemy, Sincock, Liu, Geetan, + Draper, Gill (2022). DOI: 10.30632/PJV63N6-2022a7. Petrophysics Vol. 63 No. 6 (Dec 2022) — Best + Papers of the 2022 SPWLA Annual Symposium special issue. +src2024_04/chen_sem_pore_segmentation -- Chen et al., "Pore Identification and Quantitative + Characterization of Shale SEM Images using a Deep-Learning Semantic Segmentation Pore-Net Model", + Petrophysics, Vol. 65, No. 2 (April 2024), pp. 233-245. +src2024_06/article2 -- Strobel, J. (2024). "Petrophysical Analyses for Supporting the Search for a + Claystone-Hosted Nuclear Repository." Petrophysics 65(3), 302-316. DOI: 10.30632/PJV65N3-2024a2. +src2024_10/rddtw_depth_matching -- Core-Log Depth Adaptive Matching Using RDDTW. Based on: Fang et + al. (2024), "Core-Log Depth Adaptive Matching Using RDDTW", Petrophysics, Vol. 65, No. 5, pp. + 835-851. +src2026_06/a03 -- Manuaba, I. B. G. H., Najrani, H., Cavalleri, C., Moge, A., and Chapura, M. + (2026). Effect of Pore-Size Distribution on Fluid Movement in Complex Reservoirs. Petrophysics, + 67(3), 509-524. DOI: 10.30632/PJV67N3-2026a3 (orig. SPE-227259-MS). """ from __future__ import annotations diff --git a/petrolib/depth_correction.py b/petrolib/depth_correction.py index 888b347..43d7a68 100644 --- a/petrolib/depth_correction.py +++ b/petrolib/depth_correction.py @@ -10,6 +10,24 @@ the surface tally as reading short (pipe/cable is longer downhole) and **adds** the corrections, while ``'payout'`` treats paid-out cable length as overstating the tool depth and **subtracts** them -- both are used in the corpus. + +References +---------- +Complete citations for the source tags used in this module (SPWLA journal +*Petrophysics*): + +src2016_06/article5_wireline_depth_elastic_stretch -- Article 5: Wireline Logging Depth Quality + Improvement: Methodology Review and Elastic-Stretch Correction. Bolt (2016). Petrophysics Vol. + 57, No. 3 (June 2016), pp. 294-310. DOI: none assigned (this issue predates SPWLA DOI + assignment). +src2017_12/article2_drillers_depth_waypoint -- Article 2: Driller's Depth Quality Improvement: Way- + Point Methodology. Bolt (2017). Petrophysics Vol. 58, No. 6 (December 2017), pp. 564-575. DOI: + none assigned (this issue predates SPWLA DOI assignment). +src2019_02/article6_depth_love_hate_essay -- Article 6: Depth: A Love and Hate Story. Theys (2019). + DOI: 10.30632/PJV60N1Y2019a5. Petrophysics Vol. 60 No. 1 (Feb 2019). +src2019_02/article8_drillers_depth_correction -- Article 8: Correction of Driller's Depth: Field + Example Using Driller's Way-Point Depth Correction Methodology. Bolt (2019). DOI: + 10.30632/PJV60N1Y2019a7. Petrophysics Vol. 60 No. 1 (Feb 2019). """ from __future__ import annotations @@ -36,6 +54,9 @@ def elastic_stretch( ``force`` is the axial load (N), ``length`` the suspended length (m), ``area`` the metal cross-section (m^2), ``E`` Young's modulus (Pa). + + Sources: src2017_12/article2_drillers_depth_waypoint, + src2019_02/article6_depth_love_hate_essay, src2019_02/article8_drillers_depth_correction. """ return np.asarray(_arr(force) * _arr(length) / (E * _arr(area))) @@ -54,6 +75,9 @@ def distributed_stretch( ``w`` carrying an ``end_load`` ``F`` at the bottom: the linear term is the end load, the quadratic term the string's own weight (scaled by the ``buoyancy`` factor). ``ea`` is the lumped ``E*A`` stiffness. + + Sources: src2016_06/article5_wireline_depth_elastic_stretch, + src2019_02/article8_drillers_depth_correction. """ length_a = _arr(length) return np.asarray( @@ -67,6 +91,9 @@ def thermal_elongation(length: ArrayLike, dT: ArrayLike, *, alpha: float = ALPHA ``dT`` is the temperature rise over the calibration temperature; ``alpha`` the linear expansion coefficient (1/K). + + Sources: src2017_12/article2_drillers_depth_waypoint, + src2019_02/article6_depth_love_hate_essay, src2019_02/article8_drillers_depth_correction. """ return np.asarray(alpha * _arr(length) * _arr(dT)) @@ -82,6 +109,8 @@ def cable_tension( The tension at depth ``z`` supports the tool weight plus the buoyant weight of the cable hanging below it (``L = total_depth``), so it is greatest at surface and equals ``tool_weight`` at the tool. + + Sources: src2016_06/article5_wireline_depth_elastic_stretch. """ return np.asarray(tool_weight + cable_weight_per_length * (total_depth - _arr(depth))) @@ -97,6 +126,8 @@ def corrected_depth( ``convention='tally'`` adds the corrections (surface tally reads short); ``convention='payout'`` subtracts them (paid-out length overstates depth). + + Sources: src2016_06/article5_wireline_depth_elastic_stretch. """ measured_a = _arr(measured) total = _arr(stretch) + _arr(thermal) diff --git a/petrolib/depth_matching.py b/petrolib/depth_matching.py index bab67cc..9188fbc 100644 --- a/petrolib/depth_matching.py +++ b/petrolib/depth_matching.py @@ -14,6 +14,39 @@ Sign convention: a returned lag/shift is the value to feed back into :func:`apply_integer_shift` / :func:`apply_depth_shift` to align the target onto the reference; a positive integer lag moves the target to greater depth (index). + +References +---------- +Complete citations for the source tags used in this module (SPWLA journal +*Petrophysics*): + +src2018_12/article10_ml_depth_matching -- Article 10: Machine-Learning-Based Automatic Well-Log + Depth Matching. Zimmermann, Liang, Zeroug (2018). DOI: 10.30632/PJV59N6Y2018a9. Petrophysics Vol. + 59 No. 6 (Dec 2018) — Special Issue: Data-Driven Analytics in Logging and Petrophysics. +src2019_08/article1_ml_well_log_correlation -- Article 1: A Machine-Learning-Based Approach to + Assistive Well-Log Correlation. Brazell, Bayeh, Ashby, Burton (2019). DOI: + 10.30632/PJV60N4-2019a1. Petrophysics Vol. 60 No. 4 (Aug 2019). +src2019_10/article3_ml_depth_matching -- Article 3: A Machine-Learning Framework for Automating + Well-Log Depth Matching. Le, Liang, Zimmermann, Zeroug, Heliot (2019). DOI: + 10.30632/PJV60N5-2019a3. Petrophysics Vol. 60 No. 5 (Oct 2019). +src2022_02/article3_log_analytics_dtw_xcorr -- Article 3: Automated Log Data Analytics Workflow - + The Value of Data Access and Management to Reduced Turnaround Time for Log Analysis. Torres + Caceres, Duffaut, Westad, Stovas, Johansen, Jenssen (2022). DOI: 10.30632/PJV63N1-2022a3. + Petrophysics Vol. 63 No. 1 (Feb 2022). +src2023_02/article9_depth_matching -- Article 9: Automated Well-Log Pattern Alignment and Depth- + Matching Techniques: An Empirical Review and Recommendations. Ezenkwu, Guntoro, Starkey, Vaziri, + Addario (2023). DOI: 10.30632/PJV64N1-2023a9. Petrophysics Vol. 64 No. 1 (Feb 2023). +src2025_06/toc_prediction -- Comparative Analysis of TOC Logging Evaluation Methods Using Machine + Learning Implements the methodology from: Dong, M., Shang, J., Tian, L., Wu, M., and Nie, X., + 2025, "Comparative Analysis of TOC Logging Evaluation Methods Using Machine Learning – A Case + Study of the Ordos Basin-Yanchang Formation," Petrophysics, Vol. 66, No. 3, pp. 425–448. +src2026_02/depth_alignment -- Article 4: Dynamic Depth Alignment of Well Logs: A Continuous + Optimization Framework for Enhanced Petrophysical and Rock Physics Interpretation. Westeng et al. + (2026), Petrophysics, 67(1), 54-67. DOI: 10.30632/PJV67N1-2026a4. +src2026_04/a12_depth_shifting_ml -- Pan, W., Fu, L., Xu, C., Ashby, M., Lee, H., Lee, J., Meng, F., + Chen, S., Ye, Y., Jiang, H., Kim, H., Kong, H., Baek, I., Baek, J., Sun, X., Sun, H., Li, S., + Zhao, Z., Ke, Y., ... and Park, J. (2026). Automatic Well-Log Depth Shifting With Data-Driven + Approaches: A Contest Summary. Petrophysics, 67(2), 437–462. DOI: 10.30632/PJV67N2-2026a12. """ from __future__ import annotations @@ -74,6 +107,10 @@ def dtw( (``cost='absdiff'``) difference. ``band`` is the Sakoe-Chiba half-width (``None`` = full). Returns the total ``distance`` (``sqrt`` of it if ``root=True``), the backtracked 0-based ``path`` and the accumulated matrix. + + Sources: src2018_12/article10_ml_depth_matching, + src2019_08/article1_ml_well_log_correlation, src2019_10/article3_ml_depth_matching, + src2022_02/article3_log_analytics_dtw_xcorr, src2023_02/article9_depth_matching. """ x = _arr(ref) y = _arr(target) @@ -162,6 +199,8 @@ def warp_to_reference( For each reference index the matched ``target`` samples are combined (``reduce='mean'``); reference indices absent from the path are filled from the nearest populated index. + + Sources: src2023_02/article9_depth_matching. """ if reduce != "mean": raise ValueError(f"unknown reduce {reduce!r}; use 'mean'") @@ -183,7 +222,10 @@ def warp_to_reference( def path_depth_shifts( path: list[tuple[int, int]], depth_ref: ArrayLike, depth_target: ArrayLike ) -> tuple[_Float, _Float]: - """Per-depth correction from a DTW path: ``(depth_ref[i], depth_target[j]-depth_ref[i])``.""" + """Per-depth correction from a DTW path: ``(depth_ref[i], depth_target[j]-depth_ref[i])``. + + Sources: src2026_04/a12_depth_shifting_ml. + """ dref = _arr(depth_ref) dtgt = _arr(depth_target) depths = np.array([dref[i] for i, _ in path]) @@ -209,6 +251,8 @@ def cow( Greedily adjusts ``n_segments`` interior segment boundaries of ``target`` within +/-``slack`` to maximise the piecewise segment correlation with ``ref``, then piecewise-linearly remaps ``target`` onto the reference grid. + + Sources: src2023_02/article9_depth_matching. """ x = _arr(ref) y = _arr(target) @@ -249,6 +293,10 @@ def xcorr_shift( ``edge='trim'`` correlates only the overlapping samples; ``edge='wrap'`` uses a circular ``np.roll``. Returns the best ``lag``, its correlation and (if ``return_curve``) the full correlation-vs-lag curve. + + Sources: src2018_12/article10_ml_depth_matching, + src2019_08/article1_ml_well_log_correlation, src2019_10/article3_ml_depth_matching, + src2026_04/a12_depth_shifting_ml. """ x = _arr(ref) y = _arr(target) @@ -290,6 +338,8 @@ def xcorr_shift_depth( the shifted ``depth_a`` and maximising the Pearson correlation (its absolute value if ``use_abs_corr``). ``b`` may be a single curve or ``(n, k)`` multi-curve array. Returns ``(best_shift, best_corr)``. + + Sources: src2025_06/toc_prediction. """ da = _arr(depth_a) av = _arr(a) @@ -323,6 +373,8 @@ def local_shifts( Over sliding windows (length ``window``, stride ``step``) picks the lag that maximises the mean-removed full cross-correlation, clipped to ``[-max_lag, max_lag]``. + + Sources: src2018_12/article10_ml_depth_matching. """ r = _arr(ref) t = _arr(target) @@ -345,6 +397,8 @@ def apply_integer_shift(log: ArrayLike, lag: int, *, fill: float = np.nan) -> _F A positive ``lag`` moves samples to greater depth (index); the exposed edge is filled with ``fill``. + + Sources: src2026_04/a12_depth_shifting_ml. """ x = _arr(log) n = x.size @@ -362,6 +416,8 @@ def apply_depth_shift(values: ArrayLike, depth: ArrayLike, shift: ArrayLike) -> Resamples ``values`` from ``depth + shift`` back onto ``depth`` with endpoint clamping; ``shift`` may be a scalar bulk shift or a per-sample array. + + Sources: src2026_02/depth_alignment. """ v = _arr(values) z = _arr(depth) diff --git a/petrolib/em_dielectric.py b/petrolib/em_dielectric.py index 8985f8c..d2d7b98 100644 --- a/petrolib/em_dielectric.py +++ b/petrolib/em_dielectric.py @@ -20,6 +20,119 @@ Constants: ``EPS0`` (vacuum permittivity, F/m) and ``MU0`` (vacuum permeability, H/m). + +References +---------- +Complete citations for the source tags used in this module (SPWLA journal +*Petrophysics*): + +src2014_04/article5_deepwater_formation_evaluation -- Article 5: Formation-Evaluation Challenges + and Opportunities in Deepwater Roland Chemali, Wade Samec, Ron Balliet, Paul Cooper, David + Torres, Chris Jones (2014). Petrophysics Vol. 55, No. 2 (April 2014), pp. 124-135. DOI: none + assigned (this issue predates SPWLA DOI assignment). +src2014_08/article5_dielectric_permittivity_shales -- Article 5: Dielectric Permittivity: A + Petrophysical Parameter for Shales. Matthew Josh (2014). Petrophysics Vol. 55, No. 4 (August + 2014), pp. 319-332. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2014_10/article1_lwd_inversion_anisotropy -- Article 1: Inversion-Based Interpretation of + Logging-While-Drilling Resistivity and Nuclear Measurements: Field Examples in High-Angle and + Horizontal Wells Olabode Ijasan, Carlos Torres-Verdin, William E. Preeg, John Rasmus, Edward J. + Stockhausen (2014). Petrophysics Vol. 55, No. 5 (October 2014), pp. 374-391. DOI: none assigned + (this issue predates SPWLA DOI assignment). +src2014_10/article6_dielectric_oil_movability -- Article 6: Application of an Oil-Movability + Quicklook Technique Using Dielectric Measurements at Four Depths of Investigation. S.T. Grayson + and J.L. Hemingway (2014). Petrophysics Vol. 55, No. 5 (October 2014), pp. 461-469. DOI: none + assigned (this issue predates SPWLA DOI assignment). +src2014_12/article3_nmr_dielectric_limestone -- Article 3: Experimental Study of the Effects of + Wettability and Fluid Saturation on NMR and Dielectric Measurements in Limestone Lalitha + Venkataramanan, Martin D. Hurlimann, Jeffrey A. Tarvin, Kamilla Fellah, Diana Acero-Allard, + Nikita V. Seleznev (2014). Petrophysics Vol. 55, No. 6 (December 2014), pp. 572-586. DOI: none + assigned (this issue predates SPWLA DOI assignment). +src2014_12/article4_porescale_dielectric -- Article 4: Pore-Scale Evaluation of Dielectric + Measurements in Formations with Complex Pore and Grain Structures. Huangye Chen and Zoya Heidari + (2014). Petrophysics Vol. 55, No. 6 (December 2014), pp. 587-597. DOI: none assigned (this issue + predates SPWLA DOI assignment). +src2014_12/article6_array_induction_geometric_factors -- Article 6: Reminiscences on the + Development of the First Commercial Array-Induction Measurement. Peter Elkington (2014). + Petrophysics Vol. 55, No. 6 (December 2014), pp. 618-623. DOI: none assigned (this issue predates + SPWLA DOI assignment). +src2016_02/article5_shaly_sand_graphical_solutions -- Article 5: Graphical Solutions for Laminated + and Dispersed Shaly Sands. Bootle (2016). Petrophysics Vol. 57, No. 1 (February 2016), pp. 51-59. + DOI: none assigned (this issue predates SPWLA DOI assignment). +src2016_10/article1_emla_lookahead_resistivity -- Article 1: Looking Ahead of the Bit While + Drilling: From Vision to Reality. Constable, Antonsen, Stalheim, Olsen, Fjell, Dray, Eikenes, + Aarflot, Haldorsen, Digranes, Seydoux, Omeragic, Thiel, Davydychev, Denichou, Salim, Frey, Homan, + Tan (2016). Petrophysics Vol. 57, No. 5 (October 2016), pp. 426-446. DOI: none assigned (this + issue predates SPWLA DOI assignment). +src2016_10/article4_dielectric_archie_greenriver -- Article 4: Advanced Log Interpretation in Field + Development. Merkel, Lessenger (2016). Petrophysics Vol. 57, No. 5 (October 2016), pp. 479-491. + DOI: none assigned (this issue predates SPWLA DOI assignment). +src2017_06/article5_complex_resistivity_dispersion -- Article 5: Borehole Measurements of the + Complex-Resistivity Dispersion Spectrum: A New Logging Method to Identify Low-Resistivity + Reservoirs. Jiang, Ke, Kang, Sun, Yin (2017). Petrophysics Vol. 58, No. 3 (June 2017), pp. + 281-288. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2018_04/article6_dielectric_matrix_crim_cda -- Article 6: Improving Dielectric Interpretation by + Calibrating Matrix Permittivity and Solving Dielectric Mixing Laws With a New Graphical Method. + Wang, Wang, Toumelin, Brown, Crousse (2018). DOI: 10.30632/PJV59N2-2018a5. Petrophysics Vol. 59 + No. 2 (Apr 2018). +src2018_04/article7_bakken_dielectric_dispersion -- Article 7: Bakken Petroleum System + Characterization Using Dielectric-Dispersion Logs. Han, Misra (2018). DOI: + 10.30632/PJV59N2-2018a6. Petrophysics Vol. 59 No. 2 (Apr 2018). +src2018_06/article4_clay_network_resistivity_saturation -- Article 4: A New Resistivity-Based Model + for Improved Hydrocarbon Saturation Assessment in Clay-Rich Formations Using Quantitative + Geometry of the Clay Network. Garcia, Jagadisan, Rostami, Heidari (2018). DOI: + 10.30632/PJV59N3-2018a3. Petrophysics Vol. 59 No. 3 (Jun 2018). +src2018_06/article5_wideband_em_dem_permittivity -- Article 5: Coherent Interpretation of Wideband + Electromagnetic Measurements in the Millihertz to Gigahertz Frequency Range. Seleznev, Hou, + Freed, Habashy, Feng, Fellah, Xu, Nadeev (2018). DOI: 10.30632/PJV59N3-2018a4. Petrophysics Vol. + 59 No. 3 (Jun 2018). +src2019_12/article3_lwd_permittivity -- Article 3: Deducing Electrical Permittivity of Formations + From LWD Resistivity Measurements. Stalheim (2019). DOI: 10.30632/PJV60N6-2019a3. Petrophysics + Vol. 60 No. 6 (Dec 2019). +src2020_02/article2_russian_western_resistivity -- Article 2: Comparison of the Russian and Western + Resistivity Logs in Typical Western Siberian Reservoir Environments - A Numerical Study. Epov, + Sukhorukova, Nechaev, Petrov, Rabinovich, Weston, Tyurin, Wang, Abubakar, Claverie (2020). DOI: + 10.30632/PJV61N1-2020a1. Petrophysics Vol. 61 No. 1 (Feb 2020). +src2020_02/article3_hdil_array_induction_anisotropic -- Article 3: Response Characteristics of an + Array Induction Tool (HDIL) in Heterogeneous Anisotropic Formations. Liu, Zhang, Zhang, Xu, Kang, + Xiao (2020). DOI: 10.30632/PJV61N1-2020a2. Petrophysics Vol. 61 No. 1 (Feb 2020). +src2021_02/article4_obm_dielectric_fracture_fill -- Article 4: Identifying Fracture-Filling + Material in Oil-Based Mud With Dielectric Borehole Imaging. Schlicht, Zhang, Luling, Graham, + Cournot, Sadownyk (2021). DOI: 10.30632/PJV62N1-2021a3. Petrophysics Vol. 62 No. 1 (Feb 2021). +src2021_02/article8_injectite_em_3d_inversion -- Article 8: Mapping Complex Injectite Bodies With + Multiwell Electromagnetic 3D Inversion Data. Clegg, Eriksen, Best, Tollefsen, Kowicki, Marchant + (2021). DOI: 10.30632/PJV62N1-2021a7. Petrophysics Vol. 62 No. 1 (Feb 2021). +src2021_06/article5_lwd_colocated_antenna -- Article 5: First LWD Co-Located Antenna Sensors for + Real-Time Anisotropy and Dip Angle Determination, Yielding Better Look-Ahead Detection. Bittar, + Wu, Ma, Pan, Fan, Griffing, Lozinsky (2021). DOI: 10.30632/PJV62N3-2021a4. Petrophysics Vol. 62 + No. 3 (Jun 2021). +src2021_08/article1_thinly_bedded_petrophysics -- Article 1: Tutorial - Petrophysics of Thinly + Bedded Formations. Aldred (2021). DOI: 10.30632/PJV62N4-2021t1. +src2023_06/article7_dielectric_nmr -- Funk, J., Myers, M., Hathon, L. "NMR-Mapped Distributions of + Dielectric Dispersion" Petrophysics, Vol. 64, No. 3 (June 2023), pp. 421-437 DOI: + 10.30632/PJV64N3-2023a7. +src2023_08/article4_obm_imager_inversion -- Implements a simplified version of the high-definition + OBM borehole-imager forward / inverse model from: Chen, Y.-H., Zhang, T., Bloemenkamp, R., Liang, + L. (2023). "Fracture Imaging and Response Characterization of the High-Definition Oil-Based Mud + Borehole Imagers Through Modeling and Inversion", Petrophysics, Vol. 64, No. 4, pp. 544-554. DOI: + 10.30632/PJV64N4-2023a4. +src2025_04/udar_look_ahead -- UDAR Look-Ahead-While-Drilling Technology Assessment. Based on: + Cuadros et al., "Look-Ahead-While-Drilling Technology Assessment for Early Hazards Identification + in Presalt Offshore Brazil", Petrophysics, Vol. 66, No. 2, April 2025, pp. 190–211. +src2026_06/a01_carbonate_pore_type_dielectric -- AlZoukani, A. M., Al-Hamad, M., and Abdallah, W. + (2026). Unlocking the Effect of Pore Types on Dielectric Permittivity in Carbonates. + Petrophysics, 67(3), 470-481. DOI: 10.30632/PJV67N3-2026a1 (Best Petrophysics Papers from MEOS + GEO 2025; orig. SPE-227798-MS). +src2026_06/a02_mf_dielectric_fracture_sensitivity -- Al-Qouzi, W., Hassan, A., Attia, H., El- + Husseiny, A., and Mahmoud, M. (2026). Experimental Study of Sensitivity of Multifrequency (MF) + Dielectric Measurements to Hydraulic Fractures in Sandstone and Carbonate Formations. + Petrophysics, 67(3), 482-508. DOI: 10.30632/PJV67N3-2026a2 (orig. SPE-227827-MS). +src2026_06/a05_udar_anisotropy_sensitivity -- Bower, M., Xie, H., Wang, G. L., Leveque, S., and + Dolan, J. (2026). Anisotropy Sensitivity in Ultradeep Azimuthal Resistivity Technologies. + Petrophysics, 67(3), 544-559. DOI: 10.30632/PJV67N3-2026a5. +src2026_06/a09_mf_dielectric_emulsion -- Albenayyan, N., Hassan, A., El-Husseiny, A., and Mahmoud, + M. (2026). A Method to Characterize the Emulsions in Oil-Water Production Wells Using + Multifrequency Dielectric Technique. Petrophysics, 67(3), 594-618. DOI: 10.30632/PJV67N3-2026a9 + (cover paper). """ from __future__ import annotations @@ -72,6 +185,9 @@ def complex_permittivity( ``eps''`` already in permittivity units; ``sigma`` (S/m) adds the ohmic loss ``sigma/(omega*eps0)``. ``freq_hz`` is required only when ``sigma`` is nonzero. Returns a complex array in the ``-j`` engineering convention. + + Sources: src2018_04/article7_bakken_dielectric_dispersion, + src2026_06/a01_carbonate_pore_type_dielectric. """ er = _arr(eps_real) loss = _arr(eps_imag) @@ -85,25 +201,37 @@ def complex_permittivity( def imag_permittivity_from_sigma(sigma: ArrayLike, freq_hz: ArrayLike) -> _Float: - """Loss permittivity from conductivity: ``eps'' = sigma/(2*pi*f*eps0)``.""" + """Loss permittivity from conductivity: ``eps'' = sigma/(2*pi*f*eps0)``. + + Sources: src2026_06/a01_carbonate_pore_type_dielectric. + """ w = 2.0 * np.pi * _arr(freq_hz) return np.asarray(_arr(sigma) / (w * EPS0)) def sigma_from_imag_permittivity(eps_imag: ArrayLike, freq_hz: ArrayLike) -> _Float: - """Conductivity from loss permittivity: ``sigma = eps''*2*pi*f*eps0``.""" + """Conductivity from loss permittivity: ``sigma = eps''*2*pi*f*eps0``. + + Sources: src2026_06/a02_mf_dielectric_fracture_sensitivity. + """ w = 2.0 * np.pi * _arr(freq_hz) return np.asarray(_arr(eps_imag) * w * EPS0) def loss_tangent(eps_star: ArrayLike) -> _Float: - """Loss tangent ``tan(delta) = -Im(eps*)/Re(eps*)`` (-j convention).""" + """Loss tangent ``tan(delta) = -Im(eps*)/Re(eps*)`` (-j convention). + + Sources: src2026_06/a01_carbonate_pore_type_dielectric. + """ z = np.asarray(eps_star, np.complex128) return np.asarray(-z.imag / z.real) def impedivity(eps_r: ArrayLike, sigma: ArrayLike, freq_hz: ArrayLike) -> _Complex: - """Complex impedivity ``1/(j*omega*eps0*eps_r + sigma)`` (inverse admittivity).""" + """Complex impedivity ``1/(j*omega*eps0*eps_r + sigma)`` (inverse admittivity). + + Sources: src2023_08/article4_obm_imager_inversion. + """ w = 2.0 * np.pi * _arr(freq_hz) admittivity = 1j * w * EPS0 * _arr(eps_r) + _arr(sigma) return np.asarray(1.0 / admittivity, np.complex128) @@ -130,7 +258,11 @@ def water_permittivity( def debye(freq_hz: ArrayLike, *, eps_inf: float, eps_s: float, tau: float) -> _Complex: - """Single-pole Debye relaxation ``eps_inf + (eps_s-eps_inf)/(1 + j*omega*tau)``.""" + """Single-pole Debye relaxation ``eps_inf + (eps_s-eps_inf)/(1 + j*omega*tau)``. + + Sources: src2014_08/article5_dielectric_permittivity_shales, + src2023_06/article7_dielectric_nmr. + """ w = 2.0 * np.pi * _arr(freq_hz) return np.asarray(eps_inf + (eps_s - eps_inf) / (1.0 + 1j * w * tau), np.complex128) @@ -141,6 +273,9 @@ def cole_cole( """Cole-Cole relaxation with distribution exponent ``alpha`` (0 -> Debye). ``eps_inf + (eps_s-eps_inf)/(1 + (j*omega*tau)**(1-alpha))``. + + Sources: src2014_08/article5_dielectric_permittivity_shales, + src2026_06/a02_mf_dielectric_fracture_sensitivity. """ w = 2.0 * np.pi * _arr(freq_hz) jwt = 1j * w * tau @@ -159,6 +294,8 @@ def havriliak_negami( """Havriliak-Negami relaxation (``alpha=beta=1`` -> Debye). ``eps_inf + (eps_s-eps_inf)/(1 + (j*omega*tau)**alpha)**beta``. + + Sources: src2023_06/article7_dielectric_nmr. """ w = 2.0 * np.pi * _arr(freq_hz) jwt = 1j * w * tau @@ -173,6 +310,8 @@ def cole_cole_resistivity( ``rho(omega) = rho0*(1 - m*(1 - 1/(1 + (j*omega*tau)**c)))`` with DC resistivity ``rho0``, chargeability ``m``, time constant ``tau`` and frequency exponent ``c``. + + Sources: src2017_06/article5_complex_resistivity_dispersion. """ w = 2.0 * np.pi * _arr(freq_hz) jwtc = (1j * w * tau) ** c @@ -191,6 +330,10 @@ def mix_power_law(fractions: ArrayLike, eps_components: ArrayLike, *, alpha: flo Complex Refractive Index Method (CRIM / time-average of sqrt). Complex-safe: ``eps_components`` may carry loss. ``fractions`` and ``eps_components`` broadcast with the component index along ``axis=0``. + + Sources: src2014_12/article4_porescale_dielectric, + src2018_04/article6_dielectric_matrix_crim_cda, + src2021_02/article4_obm_dielectric_fracture_fill. """ f = _num(fractions) e = _num(eps_components) @@ -211,6 +354,12 @@ def crim( ``eps_mix = (phi*Sw*eps_w**a + phi*(1-Sw)*eps_hc**a + (1-phi)*eps_m**a)**(1/a)`` with ``a = alpha`` (0.5 = classic CRIM square-root mixing). + + Sources: src2014_10/article6_dielectric_oil_movability, + src2014_12/article3_nmr_dielectric_limestone, src2014_12/article4_porescale_dielectric, + src2016_10/article4_dielectric_archie_greenriver, + src2018_04/article6_dielectric_matrix_crim_cda, + src2018_04/article7_bakken_dielectric_dispersion, src2019_12/article3_lwd_permittivity. """ phi_a = _arr(phi) sw_a = _arr(sw) @@ -236,6 +385,10 @@ def sw_from_permittivity( ``Sw = (eps_meas**a - (1-phi)*eps_m**a - phi*eps_hc**a) / (phi*(eps_w**a - eps_hc**a))``. ``clip=True`` bounds the result to ``[0, 1]``. + + Sources: src2014_12/article3_nmr_dielectric_limestone, + src2014_12/article4_porescale_dielectric, src2018_04/article7_bakken_dielectric_dispersion, + src2019_12/article3_lwd_permittivity. """ em = _arr(eps_meas) phi_a = _arr(phi) @@ -258,6 +411,8 @@ def bvw_from_permittivity( """Bulk volume water ``phi*Sw`` from :func:`crim`, unclipped (salinity-robust). ``BVW = (eps_meas**a - (1-phi)*eps_m**a - phi*eps_hc**a) / (eps_w**a - eps_hc**a)``. + + Sources: src2016_10/article4_dielectric_archie_greenriver. """ em = _arr(eps_meas) phi_a = _arr(phi) @@ -277,6 +432,9 @@ def water_filled_porosity( ``phi_w = (eps_meas**a - eps_m**a) / (eps_w**a - eps_m**a)``; ``clip=True`` bounds the result to ``[0, 1]``. + + Sources: src2014_10/article6_dielectric_oil_movability, + src2018_04/article6_dielectric_matrix_crim_cda. """ em = _arr(eps_meas) phi_w = (em**alpha - eps_matrix**alpha) / (eps_w**alpha - eps_matrix**alpha) @@ -298,6 +456,9 @@ def maxwell_garnett( ``eps_eff = eps_h*(1 + f*ds/(eps_h + N*(1-f)*ds))`` where ``ds = eps_i-eps_h`` and ``N = depol`` (``1/3`` for spheres). Complex-safe -- also valid for conductivity mixing. + + Sources: src2018_06/article4_clay_network_resistivity_saturation, + src2026_06/a09_mf_dielectric_emulsion. """ eh = _num(eps_host) ei = _num(eps_incl) @@ -355,6 +516,8 @@ def depolarization_spheroid(aspect: ArrayLike) -> tuple[_Float, _Float, _Float]: ``(1/3, 1/3, 1/3)``; ``<1`` -> oblate (disk); ``>1`` -> prolate (needle). ``Lz`` is along the symmetry (polar) axis and ``Lx = Ly = (1-Lz)/2``. The three factors sum to 1. + + Sources: src2018_06/article5_wideband_em_dem_permittivity. """ r = np.asarray(aspect, np.float64) lz = np.full(r.shape, 1.0 / 3.0) @@ -387,13 +550,23 @@ def depolarization_spheroid(aspect: ArrayLike) -> tuple[_Float, _Float, _Float]: def skin_depth(rho: ArrayLike, freq_hz: ArrayLike, *, mu_r: float = 1.0) -> _Float: - """EM skin depth ``delta = sqrt(2*rho/(omega*mu))`` (``mu = mu0*mu_r``).""" + """EM skin depth ``delta = sqrt(2*rho/(omega*mu))`` (``mu = mu0*mu_r``). + + Sources: src2016_10/article1_emla_lookahead_resistivity, + src2016_10/article4_dielectric_archie_greenriver, + src2020_02/article2_russian_western_resistivity, + src2021_02/article8_injectite_em_3d_inversion, src2021_06/article5_lwd_colocated_antenna, + src2025_04/udar_look_ahead, src2026_06/a05_udar_anisotropy_sensitivity. + """ w = 2.0 * np.pi * _arr(freq_hz) return np.asarray(np.sqrt(2.0 * _arr(rho) / (w * MU0 * mu_r))) def induction_number(spacing_m: ArrayLike, rho: ArrayLike, freq_hz: ArrayLike) -> _Float: - """Induction number ``L/delta`` (near-field vs far-field discriminator).""" + """Induction number ``L/delta`` (near-field vs far-field discriminator). + + Sources: src2026_06/a05_udar_anisotropy_sensitivity. + """ return np.asarray(_arr(spacing_m) / skin_depth(rho, freq_hz)) @@ -435,12 +608,18 @@ def sigma_eps_from_wavenumber( def phase_shift_deg(rho: ArrayLike, freq_hz: ArrayLike, spacing_m: ArrayLike) -> _Float: - """Induction-limit phase shift over ``spacing_m``: ``degrees(L/delta)``.""" + """Induction-limit phase shift over ``spacing_m``: ``degrees(L/delta)``. + + Sources: src2021_06/article5_lwd_colocated_antenna. + """ return np.asarray(np.degrees(induction_number(spacing_m, rho, freq_hz))) def attenuation_db(rho: ArrayLike, freq_hz: ArrayLike, spacing_m: ArrayLike) -> _Float: - """Induction-limit amplitude attenuation over ``spacing_m``: ``8.686*L/delta`` dB.""" + """Induction-limit amplitude attenuation over ``spacing_m``: ``8.686*L/delta`` dB. + + Sources: src2021_06/article5_lwd_colocated_antenna. + """ return np.asarray(_NEPER_TO_DB * induction_number(spacing_m, rho, freq_hz)) @@ -450,6 +629,8 @@ def resistivity_from_phase( """Induction-limit inverse of :func:`phase_shift_deg` -> apparent ``rho``. ``rho = L^2*omega*mu0/(2*phase_rad^2)`` with ``phase_rad = radians(phase_deg)``. + + Sources: src2021_06/article5_lwd_colocated_antenna. """ w = 2.0 * np.pi * _arr(freq_hz) phase_rad = np.radians(_arr(phase_deg)) @@ -462,6 +643,8 @@ def attenuation_phase_from_voltages(v_near: ArrayLike, v_far: ArrayLike) -> tupl ``ratio = v_near/v_far``; ``atten_db = 20*log10|ratio|`` and ``phase_deg = degrees(angle(ratio))``. + + Sources: src2016_10/article1_emla_lookahead_resistivity. """ ratio = np.asarray(v_near, np.complex128) / np.asarray(v_far, np.complex128) atten_db = 20.0 * np.log10(np.abs(ratio)) @@ -475,12 +658,24 @@ def attenuation_phase_from_voltages(v_near: ArrayLike, v_far: ArrayLike) -> tupl def anisotropy_coefficient(rh: ArrayLike, rv: ArrayLike) -> _Float: - """Resistivity anisotropy coefficient ``lambda = sqrt(Rv/Rh)`` (canonical).""" + """Resistivity anisotropy coefficient ``lambda = sqrt(Rv/Rh)`` (canonical). + + Sources: src2014_04/article5_deepwater_formation_evaluation, + src2014_10/article1_lwd_inversion_anisotropy, + src2016_02/article5_shaly_sand_graphical_solutions, + src2020_02/article2_russian_western_resistivity, + src2020_02/article3_hdil_array_induction_anisotropic, + src2021_08/article1_thinly_bedded_petrophysics, src2026_06/a05_udar_anisotropy_sensitivity. + """ return np.asarray(np.sqrt(_arr(rv) / _arr(rh))) def apparent_resistivity_dip(rh: ArrayLike, rv: ArrayLike, dip_deg: ArrayLike) -> _Float: - """Apparent resistivity at relative dip ``theta``: ``Rh*sqrt(cos^2 + (Rv/Rh)*sin^2)``.""" + """Apparent resistivity at relative dip ``theta``: ``Rh*sqrt(cos^2 + (Rv/Rh)*sin^2)``. + + Sources: src2020_02/article3_hdil_array_induction_anisotropic, + src2021_08/article1_thinly_bedded_petrophysics. + """ rh_a = _arr(rh) rv_a = _arr(rv) theta = np.radians(_arr(dip_deg)) @@ -488,7 +683,10 @@ def apparent_resistivity_dip(rh: ArrayLike, rv: ArrayLike, dip_deg: ArrayLike) - def doll_radial_geometric_factor(r: ArrayLike, spacing_m: ArrayLike) -> _Float: - """Doll radial geometric factor ``G = r^2/(r^2 + (L/2)^2)`` (integrated to radius r).""" + """Doll radial geometric factor ``G = r^2/(r^2 + (L/2)^2)`` (integrated to radius r). + + Sources: src2014_12/article6_array_induction_geometric_factors. + """ r_a = _arr(r) half = _arr(spacing_m) / 2.0 return np.asarray(r_a**2 / (r_a**2 + half**2)) @@ -501,6 +699,8 @@ def apparent_conductivity_two_zone( ``sigma_a = G_xo*sigma_xo + (1-G_xo)*sigma_t`` with the radial geometric factor ``G_xo`` of the invasion radius from :func:`doll_radial_geometric_factor`. + + Sources: src2014_12/article6_array_induction_geometric_factors. """ g = doll_radial_geometric_factor(r_invasion, spacing_m) return np.asarray(g * _arr(sigma_xo) + (1.0 - g) * _arr(sigma_t)) diff --git a/petrolib/flow_transport.py b/petrolib/flow_transport.py index e505a9a..77b8430 100644 --- a/petrolib/flow_transport.py +++ b/petrolib/flow_transport.py @@ -41,6 +41,126 @@ correlation constants are defined — and square metres in the Darcy-law and Kozeny-Carman functions; porosity is a fraction, RQI/r35 in um. numpy-only at import; the ``fit_*`` routines use ``numpy.polyfit``. + +References +---------- +Complete citations for the source tags used in this module (SPWLA journal +*Petrophysics*): + +src2014_04/article3 -- Article 3: The Dynamics of Reservoir Fluids and their Substantial Systematic + Variations Oliver C. Mullins, Julian Y. Zuo, Kang Wang, Paul S. Hammond, Ilaria De Santo, Hadrien + Dumont, Vinay K. Mishra, Li Chen, Andrew E. Pomerantz, Chengli Dong, Hani Elshahawi, Douglas J. + Seifert (2014). Petrophysics Vol. 55, No. 2 (April 2014), pp. 96-112. DOI: none assigned (this + issue predates SPWLA DOI assignment). +src2014_10/article5 -- Article 5: Quantifying the Impact of Petrophysical Properties on Spatial + Distribution of Contrasting Nanoparticle Agents in the Near-Wellbore Region. Kai Cheng, Aderonke + Aderibigbe, Masoud Alfi, Zoya Heidari, John Killough (2014). Petrophysics Vol. 55, No. 5 (October + 2014), pp. 447-460. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2015_02/article2 -- Article 2: CO2 EOR by Diffusive Mixing in Fractured Reservoirs. Eide, + Ersland, Brattekas, Haugen, Graue, Ferno (2015). Petrophysics Vol. 56, No. 1 (February 2015), pp. + 23-31. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2015_02/article4 -- Article 4: Petrophysical Characterization of the Pore Space in Permian + Wolfcamp Rocks. Rafatian, Capsan (2015). Petrophysics Vol. 56, No. 1 (February 2015), pp. 45-57. + DOI: none assigned (this issue predates SPWLA DOI assignment). +src2015_04/article2 -- Article 2: Steady-State Stress-Dependent Permeability Measurements of Tight + Oil-Bearing Rocks. Chhatre, Braun, Sinha, Determan, Passey, Zirkle, Wood, Boros, Berry, Leonardi, + Kudva (2015). Petrophysics Vol. 56, No. 2 (April 2015), pp. 116-124. DOI: none assigned (this + issue predates SPWLA DOI assignment). +src2015_04/article3 -- Article 3: Estimation of Permeability in the McMurray Formation Using High- + Resolution Data Sources. Manchuk, Garner, Deutsch (2015). Petrophysics Vol. 56, No. 2 (April + 2015), pp. 125-139. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2015_08/article3 -- Article 3: Gas Diffusion into Oil, Reservoir Baffling and Tar Mats Analyzed + by Downhole Fluid Analysis, Pressure Transients, Core Extracts and DSTs. Achourov, Pfeiffer, + Kollien, Betancourt, Zuo, di Primio, Mullins (2015). Petrophysics Vol. 56, No. 4 (August 2015), + pp. 346-357. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2015_10/article2 -- Article 2: Differing Equilibration Times of GOR, Asphaltenes and Biomarkers + as Determined by Charge History and Reservoir Fluid Geodynamics. Wang, Kauerauf, Zuo, Chen, Dong, + Elshahawi, Mullins (2015). Petrophysics Vol. 56, No. 5 (October 2015), pp. 440-456. DOI: none + assigned (this issue predates SPWLA DOI assignment). +src2015_10/article5 -- Article 5: Integrated Petrophysical Rock Classification in the McElroy + Field, West Texas, USA. Saneifar, Skalinski, Theologou, Kenter, Cuffey, Salazar-Tio (2015). + Petrophysics Vol. 56, No. 5 (October 2015), pp. 493-510. DOI: none assigned (this issue predates + SPWLA DOI assignment). +src2015_12/article4 -- Article 4: Petrophysical Challenges in Giant Carbonate Tengiz Field, + Republic of Kazakhstan. Skalinski, Se, Playton, Theologou, Narr, Sullivan, Mallan (2015). + Petrophysics Vol. 56, No. 6 (December 2015), pp. 615-647. DOI: none assigned (this issue predates + SPWLA DOI assignment). +src2016_02/article3 -- Article 3: Low-Permeability Measurements: Insights. Profice, Hamon, Nicot + (2016). Petrophysics Vol. 57, No. 1 (February 2016), pp. 30-40. DOI: none assigned (this issue + predates SPWLA DOI assignment). +src2016_06/article1 -- Article 1: Heterogeneous Carbonate Reservoirs: Ensuring Consistency of + Subsurface Models by Maximizing the use of Saturation-Height Models and Dynamic Data. Hulea, + Frese, Ramaswami (2016). Petrophysics Vol. 57, No. 3 (June 2016), pp. 223-232. DOI: none assigned + (this issue predates SPWLA DOI assignment). +src2017_02/article3 -- Article 3: Wettability Effects on Osmosis as an Oil-Mobilization Mechanism + During Low-Salinity Waterflooding. Fredriksen, Rognmo, Sandengen, Ferno (2017). Petrophysics Vol. + 58, No. 1 (February 2017), pp. 28-35. DOI: none assigned (this issue predates SPWLA DOI + assignment). +src2017_02/article5 -- Article 5: Comparison of Four Numerical Simulators for SCAL Experiments. + Lenormand, Lorentzen, Maas, Ruth (2017). Petrophysics Vol. 58, No. 1 (February 2017), pp. 48-56. + DOI: none assigned (this issue predates SPWLA DOI assignment). +src2018_02/article3 -- Article 3: Stress Sensitivity of Mercury-Injection Measurements. Guise, + Grattoni, Allshorn, Fisher, Schiffer (2018). DOI: 10.30632/petro_059_1_a2. Petrophysics Vol. 59 + No. 1 (Feb 2018). +src2018_02/article4 -- Article 4: Microstructural Investigation of Stress-Dependent Permeability in + Tight-Oil Rocks. King, Sansone, Kortunov, Xu, Callen, Chhatre, Sahoo, Buono (2018). DOI: + 10.30632/petro_059_1_a3. Petrophysics Vol. 59 No. 1 (Feb 2018). +src2018_06/article8 -- Article 8: Saturation-Height Modeling: Assessing Capillary Pressure Stress + Corrections. Hulea (2018). DOI: 10.30632/PJV59N3-2018a7 (inferred - see note). Petrophysics Vol. + 59 No. 3 (Jun 2018). +src2018_08/article8 -- Article 8: Incorporating Flow Regimes Into Crushed-Rock Analysis to Better + Understand Matrix Permeability and Pore Structure in Shales. Royer, Hobbs, Bonar (2018). DOI: + 10.30632/PJV59V4-2018a7. Petrophysics Vol. 59 No. 4 (Aug 2018) - Special Issue on Flow + Diagnostics. +src2019_02/article2 -- Article 2: Defining Net-Pay Cutoffs in Carbonates Using Advanced + Petrophysical Methods. Skalinski, Mallan, Edwards, Sun, Toumelin, Kelly, Wushur, Sullivan (2019). + DOI: 10.30632/PJV60N1Y2019a1. Petrophysics Vol. 60 No. 1 (Feb 2019). +src2019_04/article11 -- Article 11: Loading Effects on Gas Relative Permeability of a Low- + Permeability Sandstone. Agostini, Egermann, Jeannin, Portier, Skoczylas, Wang (2019). DOI: + 10.30632/PJV60N2-2019a9. Petrophysics Vol. 60 No. 2 (Apr 2019). +src2019_06/article4 -- Article 4: Finite-Volume Computations of Shale Tortuosity and Permeability + From 3D Pore Networks Extracted From Scanning Electron Tomographic Images. Almasoodi, Reza + (2019). DOI: 10.30632/PJV60N3-2019a3. Petrophysics Vol. 60 No. 3 (Jun 2019). +src2019_06/article6 -- Article 6: Reconsidering Klinkenberg's Permeability Data. Ruth, Arabjamaloei + (2019). DOI: 10.30632/PJV60N3-2019a5. Petrophysics Vol. 60 No. 3 (Jun 2019). +src2019_10/article8 -- Article 8: Presenting a Multifaceted Approach to Unconventional Rock Typing + and Technical Validation - Case Study in the Permian Basin and Impacts on Reservoir + Characterization Workflows. Perry, Hayes (2019). DOI: 10.30632/PJV60N5-2019a8. Petrophysics Vol. + 60 No. 5 (Oct 2019). +src2019_12/article10 -- Article 10: Review of Micro/Nanofluidic Insights on Fluid Transport + Controls in Tight Rocks. Mehmani, Kelly, Torres-Verdin (2019). DOI: 10.30632/PJV60N6-2019a10. + Petrophysics Vol. 60 No. 6 (Dec 2019). +src2020_04/article3 -- Article 3: Low-Permeability Measurement on Crushed Rock: Insights. Profice, + Lenormand (2020). DOI: 10.30632/PJV61N2-2020a3. Petrophysics Vol. 61 No. 2 (Apr 2020). +src2020_04/article9 -- Article 9: Chemically Induced Formation Damage in Shale. Wick, Taneja, + Gupta, Sondergeld, Rai (2020). DOI: 10.30632/PJV61N2-2020a9. Petrophysics Vol. 61 No. 2 (Apr + 2020). +src2020_06/article3 -- Article 3: Reliable Measurement of Saturation-Dependent Relative + Permeability in Tight Gas Sand Formations. Gonzalez, Tandon, Heidari, Gramin, Merle (2020). DOI: + 10.30632/PJV61N3-2020a3. Petrophysics Vol. 61 No. 3 (Jun 2020). +src2021_12 -- Petrophysics Vol. 62 No. 6 (Dec 2021) (issue-level reference). +src2021_12/article08 -- Article 8: The Impact of Overbalanced Drilling From Exploration/Appraisal + Wells to Field Development Plan. Mohammadlou, Reppert, Del Negro, Jones (2021). DOI: + 10.30632/PJV62N6-2021a8. Petrophysics Vol. 62 No. 6 (Dec 2021). +src2022_04/article2 -- Article 2: Permeability Modeling in Clay-Rich Carbonate Reservoir. Storebo, + Meireles, Fabricius (2022). DOI: 10.30632/PJV63N2-2022a2. Petrophysics Vol. 63 No. 2 (Apr 2022). +src2022_04/article4 -- Article 4: In-Situ Visualization and Characterization of Filter-Cake + Deposition Using Time-Lapse Micro-CT Imaging. Schroeder, Torres-Verdin (2022). DOI: + 10.30632/PJV63N2-2022a4. Petrophysics Vol. 63 No. 2 (Apr 2022). +src2022_12/article7 -- Article 7: Using Digital Rock Physics to Evaluate Novel Percussion Core + Quality. Lakshtanov, Zapata, Saucier, Cook, Eve, Lancaster, Lane, Gettemy, Sincock, Liu, Geetan, + Draper, Gill (2022). DOI: 10.30632/PJV63N6-2022a7. Petrophysics Vol. 63 No. 6 (Dec 2022) — Best + Papers of the 2022 SPWLA Annual Symposium special issue. +src2023_02/article2 -- Article 2: Modeling Permeability in Different Carbonate Rock Types. + Dernaika, Masalmeh, Mansour, Al Jallad, Koronfol (2023). DOI: 10.30632/PJV64N1-2023a2. + Petrophysics Vol. 64 No. 1 (Feb 2023). +src2023_10/article_11 -- Shafiq, M. U., Ben Mahmud, H., Khan, M., Gishkori, S. N., Wang, L., and + Jamil, M. (2023). "Effect of Chelating Agents on Tight Sandstone Formation Mineralogy During + Sandstone Acidizing." Petrophysics, 64(5), 796-817. DOI: 10.30632/PJV64N5-2023a11. +src2024_10/permeability_anisotropy -- Permeability Anisotropy in Carbonates via Digital Rock + Petrophysics. Based on: Silva Junior et al. (2024), "Permeability Anisotropy in Brazilian Presalt + Carbonates at Core Scale Using Digital Rock Petrophysics", Petrophysics, Vol. 65, No. 5, pp. + 711-738. """ from __future__ import annotations diff --git a/petrolib/geochem_fluids/adsorption.py b/petrolib/geochem_fluids/adsorption.py index 60a8d8f..9bcfafd 100644 --- a/petrolib/geochem_fluids/adsorption.py +++ b/petrolib/geochem_fluids/adsorption.py @@ -8,6 +8,45 @@ BET volumes in cm3(STP)/g; SSA in m2/g; Bg the gas formation-volume factor. Sources: src2018_02/article10, src2019_06/article2, src2019_10/article2, src2020_10/article2, src2025_12/nanopore_adsorption. + +References +---------- +Complete citations for the source tags used in this module (SPWLA journal +*Petrophysics*): + +src2018_02/article10 -- Article 10: New Perspectives on the Effects of Gas Adsorption on Storage + and Production of Natural Gas From Shale Formations. Tinni, Sondergeld, Rai (2018). DOI: + 10.30632/petro_059_1_a9 (contents-only - see note). Petrophysics Vol. 59 No. 1 (Feb 2018). +src2018_02/article10_shale_gas_adsorption -- Article 10: New Perspectives on the Effects of Gas + Adsorption on Storage and Production of Natural Gas From Shale Formations. Tinni, Sondergeld, Rai + (2018). DOI: 10.30632/petro_059_1_a9 (contents-only - see note). Petrophysics Vol. 59 No. 1 (Feb + 2018). +src2019_02/article7_groningen_depth_control -- Article 7 (Technical Note): Connecting the Dots - + The Relevance of Proper Depth Control in the Discovery of the Groningen Field. Fokkema, Visser + (2019). DOI: 10.30632/PJV60N1Y2019a6. Petrophysics Vol. 60 No. 1 (Feb 2019). +src2019_06/article2 -- Article 2: Composition of the Shales in Niutitang Formation at Huijunba + Syncline and its Influence on Microscopic Pore Structure and Gas Adsorption. Fu, Xu, Tian, Qin, + Yang (2019). DOI: 10.30632/PJV60N3-2019a1. Petrophysics Vol. 60 No. 3 (Jun 2019). +src2019_06/article2_niutitang_shale_pore_adsorption -- Article 2: Composition of the Shales in + Niutitang Formation at Huijunba Syncline and its Influence on Microscopic Pore Structure and Gas + Adsorption. Fu, Xu, Tian, Qin, Yang (2019). DOI: 10.30632/PJV60N3-2019a1. Petrophysics Vol. 60 + No. 3 (Jun 2019). +src2019_10/article2 -- Article 2: More Accurate Quantification of Free and Adsorbed Gas in Shale + Reservoirs. Ansari, Merletti, Gramin, Armitage (2019). DOI: 10.30632/PJV60N5-2019a2. Petrophysics + Vol. 60 No. 5 (Oct 2019). +src2019_10/article2_free_adsorbed_gas_shale -- Article 2: More Accurate Quantification of Free and + Adsorbed Gas in Shale Reservoirs. Ansari, Merletti, Gramin, Armitage (2019). DOI: + 10.30632/PJV60N5-2019a2. Petrophysics Vol. 60 No. 5 (Oct 2019). +src2020_10/article2 -- Article 2: Classification of Adsorption Isotherm Curves for Shale Based on + Pore Structure. Tian, Chen, Yan, Deng, He (2020). DOI: 10.30632/PJV61N5-2020a2. Petrophysics Vol. + 61 No. 5 (Oct 2020). +src2020_10/article2_adsorption_isotherm_classification -- Article 2: Classification of Adsorption + Isotherm Curves for Shale Based on Pore Structure. Tian, Chen, Yan, Deng, He (2020). DOI: + 10.30632/PJV61N5-2020a2. Petrophysics Vol. 61 No. 5 (Oct 2020). +src2025_12/co2_uptake -- CO₂ Uptake Capacity Measurement in Source-Rock Shales for GCS. + Petrophysics, 66(6), 982–994. DOI: 10.30632/PJV66N6-2025a5. +src2025_12/nanopore_adsorption -- Wettability Effect on Adsorption and Capillary Condensation in + Nanopores. Petrophysics, 66(6), 1061–1071. DOI: 10.30632/PJV66N6-2025a10. """ from __future__ import annotations @@ -28,6 +67,10 @@ def langmuir( """Langmuir isotherm ``V = V_L * P/(P + P_L)`` (half capacity at ``P = P_L``). With ``rho_b`` given, returns the sorbed gas *content* ``rho_b * V_L * P/(P+P_L)``. + + Sources: src2018_02/article10_shale_gas_adsorption, + src2019_06/article2_niutitang_shale_pore_adsorption, + src2019_10/article2_free_adsorbed_gas_shale, src2025_12/co2_uptake. """ pa = np.asarray(p, np.float64) v = np.asarray(v_l, np.float64) * pa / (pa + np.asarray(p_l, np.float64)) @@ -37,7 +80,10 @@ def langmuir( def gibbs_excess(gc: ArrayLike, rho_free: ArrayLike, rho_ads: ArrayLike) -> _Float: - """Gibbs excess correction ``G_excess = Gc*(1 - rho_free/rho_adsorbed)``.""" + """Gibbs excess correction ``G_excess = Gc*(1 - rho_free/rho_adsorbed)``. + + Sources: src2019_10/article2_free_adsorbed_gas_shale. + """ return np.asarray( np.asarray(gc, np.float64) * (1.0 - np.asarray(rho_free, np.float64) / np.asarray(rho_ads, np.float64)) @@ -45,7 +91,10 @@ def gibbs_excess(gc: ArrayLike, rho_free: ArrayLike, rho_ads: ArrayLike) -> _Flo def bet_isotherm(x_rel: ArrayLike, vm: ArrayLike, c: ArrayLike) -> _Float: - """BET isotherm ``V = Vm*C*x/((1-x)*(1 + (C-1)*x))`` with ``x = P/P0``.""" + """BET isotherm ``V = Vm*C*x/((1-x)*(1 + (C-1)*x))`` with ``x = P/P0``. + + Sources: src2020_10/article2_adsorption_isotherm_classification. + """ x = np.asarray(x_rel, np.float64) vma = np.asarray(vm, np.float64) ca = np.asarray(c, np.float64) @@ -60,6 +109,8 @@ def bet_fit( Fits ``x/(V*(1-x)) = slope*x + intercept`` (least squares); ``Vm = 1/(slope+intercept)``, ``C = slope/intercept + 1``, and the specific surface area ``SSA = (Vm/22414)*NA*cross`` (m2/g) with ``cross`` in nm2 (N2 = 0.162). + + Sources: src2020_10/article2_adsorption_isotherm_classification. """ x = np.asarray(x_rel, np.float64) v = np.asarray(v_ads, np.float64) @@ -73,7 +124,11 @@ def bet_fit( def free_gas(phi: ArrayLike, sw: ArrayLike, bg: ArrayLike) -> _Float: - """Free-gas volume per bulk volume ``= phi*(1 - Sw)/Bg``.""" + """Free-gas volume per bulk volume ``= phi*(1 - Sw)/Bg``. + + Sources: src2018_02/article10_shale_gas_adsorption, + src2019_10/article2_free_adsorbed_gas_shale. + """ return np.asarray( np.asarray(phi, np.float64) * (1.0 - np.asarray(sw, np.float64)) @@ -84,7 +139,10 @@ def free_gas(phi: ArrayLike, sw: ArrayLike, bg: ArrayLike) -> _Float: def gas_in_place( area_m2: ArrayLike, h_m: ArrayLike, phi: ArrayLike, sg: ArrayLike, bg: ArrayLike ) -> _Float: - """Volumetric free gas-in-place ``= A*h*phi*Sg/Bg``.""" + """Volumetric free gas-in-place ``= A*h*phi*Sg/Bg``. + + Sources: src2019_02/article7_groningen_depth_control. + """ return np.asarray( np.asarray(area_m2, np.float64) * np.asarray(h_m, np.float64) diff --git a/petrolib/geochem_fluids/asphaltene.py b/petrolib/geochem_fluids/asphaltene.py index 6b0fa6f..ad7e7b7 100644 --- a/petrolib/geochem_fluids/asphaltene.py +++ b/petrolib/geochem_fluids/asphaltene.py @@ -9,6 +9,37 @@ densities kg/m3, T in K, delta densities and solubility parameters in SI. The full iterative FHZ solubility solver stays in its article facade. Sources: src2014_04/article4, src2017_04/article5, src2023_02/article1, src2023_10/article_10. + +References +---------- +Complete citations for the source tags used in this module (SPWLA journal +*Petrophysics*): + +src2014_04/article4 -- Article 4: Fault Block Migrations Inferred from Asphaltene Gradients. + Chengli Dong, Melton P. Hows, Peter M.W. Cornelisse, Hani Elshahawi (2014). Petrophysics Vol. 55, + No. 2 (April 2014), pp. 113-123. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2014_04/article4_asphaltene_fault_block_migration -- Article 4: Fault Block Migrations Inferred + from Asphaltene Gradients. Chengli Dong, Melton P. Hows, Peter M.W. Cornelisse, Hani Elshahawi + (2014). Petrophysics Vol. 55, No. 2 (April 2014), pp. 113-123. DOI: none assigned (this issue + predates SPWLA DOI assignment). +src2017_04/article5 -- Article 5: Scanning Electron Micrographs of Tar-Mat Intervals Formed by + Asphaltene Phase Transition. Pfeiffer, Di Primio, Achourov, Mullins (2017). Petrophysics Vol. 58, + No. 2 (April 2017), pp. 141-152. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2017_04/article5_tarmat_asphaltene_phase -- Article 5: Scanning Electron Micrographs of Tar-Mat + Intervals Formed by Asphaltene Phase Transition. Pfeiffer, Di Primio, Achourov, Mullins (2017). + Petrophysics Vol. 58, No. 2 (April 2017), pp. 141-152. DOI: none assigned (this issue predates + SPWLA DOI assignment). +src2023_02/article1 -- Article 1: Enigmatic Reservoir Properties Deciphered Using Petroleum System + Modeling and Reservoir Fluid Geodynamics. Pierpont, Birkeland, Cely, Yang, Chen, Achourov, + Betancourt, Canas, Forsythe, Pomerantz, Yang, Datir, Mullins (2023). DOI: + 10.30632/PJV64N1-2023a1. Petrophysics Vol. 64 No. 1 (Feb 2023). +src2023_02/article1_rfg_petroleum_system -- Article 1: Enigmatic Reservoir Properties Deciphered + Using Petroleum System Modeling and Reservoir Fluid Geodynamics. Pierpont, Birkeland, Cely, Yang, + Chen, Achourov, Betancourt, Canas, Forsythe, Pomerantz, Yang, Datir, Mullins (2023). DOI: + 10.30632/PJV64N1-2023a1. Petrophysics Vol. 64 No. 1 (Feb 2023). +src2023_10/article_10 -- Mohamed, T. S., Torres-Verdin, C., and Mullins, O. C. (2023). "Enhanced + Reservoir Description via Areal Data Integration and Reservoir Fluid Geodynamics: A Case Study + From Deepwater Gulf of Mexico." Petrophysics, 64(5), 773-795. DOI: 10.30632/PJV64N5-2023a10. """ from __future__ import annotations @@ -31,13 +62,19 @@ def molar_volume_from_diameter(d_m: ArrayLike) -> _Float: - """Molar volume (m3/mol) of a sphere of diameter ``d_m`` ``= (pi/6)*d**3 * NA``.""" + """Molar volume (m3/mol) of a sphere of diameter ``d_m`` ``= (pi/6)*d**3 * NA``. + + Sources: src2014_04/article4_asphaltene_fault_block_migration. + """ d = np.asarray(d_m, np.float64) return np.asarray(np.pi / 6.0 * d**3 * N_AVOGADRO) def diameter_from_molar_volume(va_m3mol: ArrayLike) -> _Float: - """Sphere diameter (m) from molar volume ``= (6*(Va/NA)/pi)**(1/3)``.""" + """Sphere diameter (m) from molar volume ``= (6*(Va/NA)/pi)**(1/3)``. + + Sources: src2014_04/article4_asphaltene_fault_block_migration. + """ va = np.asarray(va_m3mol, np.float64) return np.asarray((6.0 * (va / N_AVOGADRO) / np.pi) ** (1.0 / 3.0)) @@ -57,6 +94,9 @@ def fhz_ratio( with ``dz`` positive downward, ``delta_rho = rho_asphaltene - rho_oil`` (kg/m3), ``Va`` in m3/mol, ``dsol2_pa`` the solubility-squared difference (Pa). The entropy and solubility terms default off (gravity-only). + + Sources: src2014_04/article4_asphaltene_fault_block_migration, + src2017_04/article5_tarmat_asphaltene_phase, src2023_02/article1_rfg_petroleum_system. """ va = np.asarray(va_m3mol, np.float64) rt = R_GAS * np.asarray(temp_k, np.float64) @@ -89,6 +129,8 @@ def fhz_invert_molar_volume( """Recover the asphaltene molar volume (m3/mol) from two OD/depth points. Inverts the gravity-only FHZ ratio: ``Va = R*T*ln(OD2/OD1)/(g*delta_rho*(z2 - z1))``. + + Sources: src2014_04/article4_asphaltene_fault_block_migration. """ rt = R_GAS * np.asarray(temp_k, np.float64) num = rt * np.log(np.asarray(od2, np.float64) / np.asarray(od1, np.float64)) diff --git a/petrolib/geochem_fluids/brine.py b/petrolib/geochem_fluids/brine.py index 9271fa3..4cf36f2 100644 --- a/petrolib/geochem_fluids/brine.py +++ b/petrolib/geochem_fluids/brine.py @@ -10,6 +10,40 @@ Celsius (the corpus uses a 7.0 variant in one file -- pass it via ``c=``). Sources: src2015_06/article4, src2015_08/article5, src2020_12/article2, src2023_08/article1, src2023_10/article_01, src2026_06/a03. + +References +---------- +Complete citations for the source tags used in this module (SPWLA journal +*Petrophysics*): + +src2015_06/article4 -- Article 4 (Technical Note): The Bateman-Konen Resistivity-Salinity + Transform. Kennedy (2015). Petrophysics Vol. 56, No. 3 (June 2015), pp. 282-283. DOI: none + assigned (this issue predates SPWLA DOI assignment). +src2015_06/article4_bateman_konen_transform -- Article 4 (Technical Note): The Bateman-Konen + Resistivity-Salinity Transform. Kennedy (2015). Petrophysics Vol. 56, No. 3 (June 2015), pp. + 282-283. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2015_08/article5 -- Article 5 (Technical Note): The Bateman-Konen Resistivity-Salinity Transform + II. Kennedy (2015). Petrophysics Vol. 56, No. 4 (August 2015), pp. 379-381. DOI: none assigned + (this issue predates SPWLA DOI assignment). +src2015_08/article5_bateman_konen_resistivity_salinity -- Article 5 (Technical Note): The Bateman- + Konen Resistivity-Salinity Transform II. Kennedy (2015). Petrophysics Vol. 56, No. 4 (August + 2015), pp. 379-381. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2020_12/article2 -- Article 2: Formation Chlorine Measurement From Spectroscopy Enables Water + Salinity Interpretation: Theory, Modeling, and Applications. Miles, Mosse, Grau (2020). DOI: + 10.30632/PJV61N6-2020a2. Petrophysics Vol. 61 No. 6 (Dec 2020). +src2023_08/article1 -- Fitz, D.E. (2023). "Evolution of Casedhole Nuclear Surveillance Logging + Through Time", Petrophysics, Vol. 64, No. 4 (August 2023), pp. 473-501. DOI: + 10.30632/PJV64N4-2023a1. +src2023_10/article_01 -- Laronga, R., Borchardt, E., Hill, B., Velez, E., Klemin, D., Haddad, S., + Haddad, E., Chadwick, C., Mahmoodaghdam, E., and Hamichi, F. (2023). "Integrated Formation + Evaluation for Site-Specific Evaluation, Optimization, and Permitting of Carbon Storage + Projects." Petrophysics, 64(5), 580-620. DOI: 10.30632/PJV64N5-2023a1. +src2025_10/a1_log_interpretation -- Article 1: Log Interpretation for Petrophysical and Elastic + Properties of Fine-Grained Sedimentary Rocks Authors: Ermis Proestakis and Ida Lykke Fabricius + Ref: Petrophysics, Vol. 66, No. 5 (October 2025), pp. 705-727. DOI: 10.30632/PJV66N5-2025a1. +src2026_06/a03 -- Manuaba, I. B. G. H., Najrani, H., Cavalleri, C., Moge, A., and Chapura, M. + (2026). Effect of Pore-Size Distribution on Fluid Movement in Complex Reservoirs. Petrophysics, + 67(3), 509-524. DOI: 10.30632/PJV67N3-2026a3 (orig. SPE-227259-MS). """ from __future__ import annotations @@ -33,13 +67,19 @@ def _arps_c(unit: str) -> float: def rw75_from_salinity(nacl_ppm: ArrayLike) -> _Float: - """Bateman-Konen water resistivity at 75 degF ``R75 = 0.0123 + 3647.5/C**0.955``.""" + """Bateman-Konen water resistivity at 75 degF ``R75 = 0.0123 + 3647.5/C**0.955``. + + Sources: src2015_06/article4_bateman_konen_transform. + """ c = np.asarray(nacl_ppm, np.float64) return np.asarray(0.0123 + 3647.5 / c**0.955) def salinity_from_rw75(rw75_ohmm: ArrayLike) -> _Float: - """NaCl ppm from the 75 degF resistivity -- exact inverse of ``rw75_from_salinity``.""" + """NaCl ppm from the 75 degF resistivity -- exact inverse of ``rw75_from_salinity``. + + Sources: src2015_06/article4_bateman_konen_transform. + """ r = np.asarray(rw75_ohmm, np.float64) return np.asarray((3647.5 / (r - 0.0123)) ** (1.0 / 0.955)) @@ -49,6 +89,8 @@ def arps_correct(r1: ArrayLike, t1: ArrayLike, t2: ArrayLike, *, unit: str = "F" ``c`` is 6.77 for ``unit="F"`` or 21.5 for ``unit="C"``. Applies equally to conductivity with the roles of R inverted by the caller. + + Sources: src2015_06/article4_bateman_konen_transform, src2025_10/a1_log_interpretation. """ c = _arps_c(unit) r1a = np.asarray(r1, np.float64) @@ -60,6 +102,8 @@ def rw_from_salinity(nacl_ppm: ArrayLike, temp: ArrayLike, *, unit: str = "F") - Computes R75 (Bateman-Konen) then Arps-corrects from 75 degF to ``temp``. ``unit="C"`` converts ``temp`` to Fahrenheit first (75 degF reference kept). + + Sources: src2015_08/article5_bateman_konen_resistivity_salinity. """ rw75 = rw75_from_salinity(nacl_ppm) t = np.asarray(temp, np.float64) @@ -68,7 +112,10 @@ def rw_from_salinity(nacl_ppm: ArrayLike, temp: ArrayLike, *, unit: str = "F") - def salinity_from_rw(rw: ArrayLike, temp: ArrayLike, *, unit: str = "F") -> _Float: - """NaCl ppm from water resistivity at ``temp`` -- inverse of ``rw_from_salinity``.""" + """NaCl ppm from water resistivity at ``temp`` -- inverse of ``rw_from_salinity``. + + Sources: src2015_08/article5_bateman_konen_resistivity_salinity. + """ t = np.asarray(temp, np.float64) t_f = t if unit == "F" else t * 9.0 / 5.0 + 32.0 rw75 = arps_correct(rw, t_f, 75.0, unit="F") diff --git a/petrolib/geochem_fluids/contamination.py b/petrolib/geochem_fluids/contamination.py index ebf603f..4dc6a55 100644 --- a/petrolib/geochem_fluids/contamination.py +++ b/petrolib/geochem_fluids/contamination.py @@ -7,6 +7,46 @@ Unit-neutral; ``eta`` is the filtrate (contamination) fraction. Sources: src2015_06/article2, src2017_08/article5, src2018_10/article6, src2021_02/article5, src2024_02/article2. + +References +---------- +Complete citations for the source tags used in this module (SPWLA journal +*Petrophysics*): + +src2015_06/article2 -- Article 2: A Breakthrough in Accurate Downhole Fluid Sample Contamination + Prediction in Real Time. Zuo, Gisolf, Dumont, Dubost, Pfeiffer, Wang, Mishra, Chen, Mullins, + Biagi, Gemelli (2015). Petrophysics Vol. 56, No. 3 (June 2015), pp. 251-265. DOI: none assigned + (this issue predates SPWLA DOI assignment). +src2015_06/article2_fluid_contamination_prediction -- Article 2: A Breakthrough in Accurate + Downhole Fluid Sample Contamination Prediction in Real Time. Zuo, Gisolf, Dumont, Dubost, + Pfeiffer, Wang, Mishra, Chen, Mullins, Biagi, Gemelli (2015). Petrophysics Vol. 56, No. 3 (June + 2015), pp. 251-265. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2017_08/article5 -- Article 5: Advances in Quantification of Miscible Contamination in + Hydrocarbon and Water Samples From Downhole to Surface Laboratories. Zuo, Gisolf, Pfeiffer, + Achourov, Chen, Mullins, Edmundson, Partouche (2017). Petrophysics Vol. 58, No. 4 (August 2017), + pp. 397-410. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2017_08/article5_contamination_quantification -- Article 5: Advances in Quantification of + Miscible Contamination in Hydrocarbon and Water Samples From Downhole to Surface Laboratories. + Zuo, Gisolf, Pfeiffer, Achourov, Chen, Mullins, Edmundson, Partouche (2017). Petrophysics Vol. + 58, No. 4 (August 2017), pp. 397-410. DOI: none assigned (this issue predates SPWLA DOI + assignment). +src2018_10/article6 -- Article 6: Proxy-Enabled Stochastic Interpretation of Downhole Fluid + Sampling Under Immiscible Flow Conditions. Kristensen, Chugunov, Cig, Jackson (2018). DOI: + 10.30632/PJV59N5-2018a5. Petrophysics Vol. 59 No. 5 (Oct 2018) - "Best of 2018 SPWLA Symposium" + issue. +src2018_10/article6_proxy_stochastic_fluid_sampling -- Article 6: Proxy-Enabled Stochastic + Interpretation of Downhole Fluid Sampling Under Immiscible Flow Conditions. Kristensen, Chugunov, + Cig, Jackson (2018). DOI: 10.30632/PJV59N5-2018a5. Petrophysics Vol. 59 No. 5 (Oct 2018) - "Best + of 2018 SPWLA Symposium" issue. +src2021_02/article5 -- Article 5: Innovative Formation Tester Sampling Procedures for Carbon + Dioxide and Other Reactive Components. Piazza, Vieira, Sacorague, Jones, Dai, Pearl, Aguiar + (2021). DOI: 10.30632/PJV62N1-2021a4. Petrophysics Vol. 62 No. 1 (Feb 2021). +src2021_02/article5_formation_tester_co2_sampling -- Article 5: Innovative Formation Tester + Sampling Procedures for Carbon Dioxide and Other Reactive Components. Piazza, Vieira, Sacorague, + Jones, Dai, Pearl, Aguiar (2021). DOI: 10.30632/PJV62N1-2021a4. Petrophysics Vol. 62 No. 1 (Feb + 2021). +src2024_02/article2 -- Article 2: Fluid Contamination Transient Analysis Gelvez and Torres-Verdín + (Petrophysics, Vol. 65, No. 1, Feb 2024, pp. 32-50). """ from __future__ import annotations @@ -18,13 +58,20 @@ def mix_linear(p_v: ArrayLike, p_f: ArrayLike, eta: ArrayLike) -> _Float: - """Linear mixing ``P = (1 - eta)*P_virgin + eta*P_filtrate``.""" + """Linear mixing ``P = (1 - eta)*P_virgin + eta*P_filtrate``. + + Sources: src2015_06/article2_fluid_contamination_prediction, + src2017_08/article5_contamination_quantification. + """ e = np.asarray(eta, np.float64) return np.asarray((1.0 - e) * np.asarray(p_v, np.float64) + e * np.asarray(p_f, np.float64)) def contamination_fraction(p: ArrayLike, p_v: ArrayLike, p_f: ArrayLike) -> _Float: - """Contamination fraction ``eta = (P - P_v)/(P_f - P_v)`` (inverse of the mixing rule).""" + """Contamination fraction ``eta = (P - P_v)/(P_f - P_v)`` (inverse of the mixing rule). + + Sources: src2015_06/article2_fluid_contamination_prediction. + """ pv = np.asarray(p_v, np.float64) return np.asarray((np.asarray(p, np.float64) - pv) / (np.asarray(p_f, np.float64) - pv)) @@ -35,6 +82,9 @@ def cleanup_powerlaw( """Power-law cleanup ``eta(V) = eta0*(1 + V/V_star)**(-exponent)``. The default exponent 5/12 is the wireline-cleanup value (2/3 for radial). + + Sources: src2018_10/article6_proxy_stochastic_fluid_sampling, + src2021_02/article5_formation_tester_co2_sampling. """ ratio = np.asarray(v, np.float64) / np.asarray(v_star, np.float64) return np.asarray(np.asarray(eta0, np.float64) * (1.0 + ratio) ** (-exponent)) @@ -46,6 +96,9 @@ def volume_to_target( """Pumped volume to reach contamination ``eta_t`` -- inverse of :func:`cleanup_powerlaw`. ``V = V_star*((eta0/eta_t)**(1/exponent) - 1)``. + + Sources: src2018_10/article6_proxy_stochastic_fluid_sampling, + src2021_02/article5_formation_tester_co2_sampling. """ ratio = np.asarray(eta0, np.float64) / np.asarray(eta_t, np.float64) return np.asarray(np.asarray(v_star, np.float64) * (ratio ** (1.0 / exponent) - 1.0)) diff --git a/petrolib/geochem_fluids/core_geochem.py b/petrolib/geochem_fluids/core_geochem.py index a291aa3..7e29b46 100644 --- a/petrolib/geochem_fluids/core_geochem.py +++ b/petrolib/geochem_fluids/core_geochem.py @@ -6,6 +6,51 @@ Unit-neutral volumes; oxides as weight fractions; ``S1`` in mg HC/g rock and ``TOC`` in wt%. Sources: src2014_10/article2, src2015_12/article3, src2016_04/article1, src2017_10/article5, src2019_02/article4, src2024_10. + +References +---------- +Complete citations for the source tags used in this module (SPWLA journal +*Petrophysics*): + +src2014_10/article2 -- Article 2: Application and Quality Control of Core Data for the Development + and Validation of Elemental Spectroscopy Log Interpretation Susan Herron, Michael Herron, Iain + Pirie, Pablo Saldungaray, Paul Craddock, Alyssa Charsky, Marina Polyakov, Frank Shray, Ting Li + (2014). Petrophysics Vol. 55, No. 5 (October 2014), pp. 392-414. DOI: none assigned (this issue + predates SPWLA DOI assignment). +src2014_10/article2_elemental_spectroscopy_qc -- Article 2: Application and Quality Control of Core + Data for the Development and Validation of Elemental Spectroscopy Log Interpretation Susan + Herron, Michael Herron, Iain Pirie, Pablo Saldungaray, Paul Craddock, Alyssa Charsky, Marina + Polyakov, Frank Shray, Ting Li (2014). Petrophysics Vol. 55, No. 5 (October 2014), pp. 392-414. + DOI: none assigned (this issue predates SPWLA DOI assignment). +src2015_12/article3 -- Article 3: Petrophysical Characterization of Bitumen-Saturated Karsted + Carbonates: Case Study of the Multibillion Barrel Upper Devonian Grosmont Formation, Northern + Alberta, Canada. MacNeil (2015). Petrophysics Vol. 56, No. 6 (December 2015), pp. 592-614. DOI: + none assigned (this issue predates SPWLA DOI assignment). +src2015_12/article3_grosmont_bitumen_carbonates -- Article 3: Petrophysical Characterization of + Bitumen-Saturated Karsted Carbonates: Case Study of the Multibillion Barrel Upper Devonian + Grosmont Formation, Northern Alberta, Canada. MacNeil (2015). Petrophysics Vol. 56, No. 6 + (December 2015), pp. 592-614. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2016_04/article1 -- Article 1: The Reservoir Producibility Index: a Metric to Assess Reservoir + Quality in Tight-Oil Plays from Logs. Reeder, Craddock, Rylander, Pirie, Lewis, Kausik, + Kleinberg, Yang, Pomerantz (2016). Petrophysics Vol. 57, No. 2 (April 2016), pp. 83-95. DOI: none + assigned (this issue predates SPWLA DOI assignment). +src2016_04/article1_reservoir_producibility_index -- Article 1: The Reservoir Producibility Index: + a Metric to Assess Reservoir Quality in Tight-Oil Plays from Logs. Reeder, Craddock, Rylander, + Pirie, Lewis, Kausik, Kleinberg, Yang, Pomerantz (2016). Petrophysics Vol. 57, No. 2 (April + 2016), pp. 83-95. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2017_10/article5 -- Article 5: Lessons Learned in Permian Core Analysis: Comparison Between + Retort, GRI, and Routine Methodologies. Blount, Croft, Driskill, Tepper (2017). Petrophysics Vol. + 58, No. 5 (October 2017), pp. 517-527. DOI: none assigned (this issue predates SPWLA DOI + assignment). +src2019_02/article4 -- Article 4: Maintaining and Reconstructing In-Situ Saturations: A Comparison + Between Whole Core, Sidewall Core, and Pressurized Sidewall Core in the Permian Basin. Blount, + McMullen, Durand, Driskill (2019). DOI: 10.30632/PJV60N1Y2019a3. Petrophysics Vol. 60 No. 1 (Feb + 2019). +src2019_02/article4_insitu_saturation_core_comparison -- Article 4: Maintaining and Reconstructing + In-Situ Saturations: A Comparison Between Whole Core, Sidewall Core, and Pressurized Sidewall + Core in the Permian Basin. Blount, McMullen, Durand, Driskill (2019). DOI: + 10.30632/PJV60N1Y2019a3. Petrophysics Vol. 60 No. 1 (Feb 2019). +src2024_10 -- Petrophysics Vol. 65 No. 5 (Oct 2024) (issue-level reference). """ from __future__ import annotations @@ -28,6 +73,9 @@ def dean_stark( Pore volume is ``v_pore`` if given, else ``v_water + v_hc``. ``phi`` is ``pore/v_bulk`` when ``v_bulk`` is given (else NaN). ``Sw = v_water/pore``, ``S_hc = v_hc/pore``. + + Sources: src2015_12/article3_grosmont_bitumen_carbonates, + src2019_02/article4_insitu_saturation_core_comparison. """ vw = np.asarray(v_water, np.float64) vh = np.asarray(v_hc, np.float64) @@ -43,6 +91,8 @@ def oxide_closure(oxides: ArrayLike, *, axis: int = -1) -> tuple[_Float, _Float] """Normalize an oxide (or elemental) suite to sum to one -> ``(closed, factor)``. ``factor = 1/sum(oxides)``; ``closed = factor*oxides``. + + Sources: src2014_10/article2_elemental_spectroscopy_qc. """ o = np.asarray(oxides, np.float64) factor = 1.0 / np.sum(o, axis=axis, keepdims=True) @@ -50,5 +100,8 @@ def oxide_closure(oxides: ArrayLike, *, axis: int = -1) -> tuple[_Float, _Float] def osi(s1_mg_g: ArrayLike, toc_wt_pct: ArrayLike) -> _Float: - """Oil saturation index ``OSI = 100*S1/TOC`` (mg HC / g TOC; Jarvie producibility).""" + """Oil saturation index ``OSI = 100*S1/TOC`` (mg HC / g TOC; Jarvie producibility). + + Sources: src2016_04/article1_reservoir_producibility_index. + """ return np.asarray(100.0 * np.asarray(s1_mg_g, np.float64) / np.asarray(toc_wt_pct, np.float64)) diff --git a/petrolib/geochem_fluids/gradients.py b/petrolib/geochem_fluids/gradients.py index fccba99..0ae90db 100644 --- a/petrolib/geochem_fluids/gradients.py +++ b/petrolib/geochem_fluids/gradients.py @@ -6,6 +6,25 @@ SI by default: depth in m, pressure in Pa (``density_from_gradient`` accepts other gradient units via ``p_unit=``). Sources: src2017_08/article4, src2021_02/article6, src2023_10/article_10. + +References +---------- +Complete citations for the source tags used in this module (SPWLA journal +*Petrophysics*): + +src2017_08/article4 -- Article 4: The Impact of Depth and Pressure Measurement Errors on the + Estimation of Pressure Gradients. Bowers, Schnacke, Hermance (2017). Petrophysics Vol. 58, No. 4 + (August 2017), pp. 376-396. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2021_02/article6 -- Article 6: Formation Evaluation With NMR, Resistivity, and Pressure Data - A + Case Study of a Carbonate Oil Field Offshore West Africa. Li, Drinkwater, Whittlesey, Condon + (2021). DOI: 10.30632/PJV62N1-2021a5. Petrophysics Vol. 62 No. 1 (Feb 2021). +src2021_02/article6_nmr_resistivity_pressure_carbonate -- Article 6: Formation Evaluation With NMR, + Resistivity, and Pressure Data - A Case Study of a Carbonate Oil Field Offshore West Africa. Li, + Drinkwater, Whittlesey, Condon (2021). DOI: 10.30632/PJV62N1-2021a5. Petrophysics Vol. 62 No. 1 + (Feb 2021). +src2023_10/article_10 -- Mohamed, T. S., Torres-Verdin, C., and Mullins, O. C. (2023). "Enhanced + Reservoir Description via Areal Data Integration and Reservoir Fluid Geodynamics: A Case Study + From Deepwater Gulf of Mexico." Petrophysics, 64(5), 773-795. DOI: 10.30632/PJV64N5-2023a10. """ from __future__ import annotations @@ -22,7 +41,10 @@ def fit_pressure_gradient(depth_m: ArrayLike, p: ArrayLike) -> tuple[float, float]: - """Least-squares pressure-depth gradient -> ``(dP/dz, P0)`` (slope, intercept).""" + """Least-squares pressure-depth gradient -> ``(dP/dz, P0)`` (slope, intercept). + + Sources: src2021_02/article6_nmr_resistivity_pressure_carbonate. + """ d = np.asarray(depth_m, np.float64) pa = np.asarray(p, np.float64) a = np.vstack([d, np.ones_like(d)]).T @@ -52,6 +74,8 @@ def fluid_contact(depth_a: ArrayLike, p_a: ArrayLike, depth_b: ArrayLike, p_b: A ``(depth_a, p_a)`` and ``(depth_b, p_b)`` are the point sets for the two fluid columns; each is fit to a line and the intersection depth returned. + + Sources: src2021_02/article6_nmr_resistivity_pressure_carbonate. """ s1, b1 = fit_pressure_gradient(depth_a, p_a) s2, b2 = fit_pressure_gradient(depth_b, p_b) diff --git a/petrolib/geochem_fluids/mudgas.py b/petrolib/geochem_fluids/mudgas.py index 12f822d..31b0f80 100644 --- a/petrolib/geochem_fluids/mudgas.py +++ b/petrolib/geochem_fluids/mudgas.py @@ -8,6 +8,25 @@ other -- the ``classify_*`` helpers below take a matching flag). Components are the light-alkane readings C1..C5 (any consistent unit). Sources: src2021_02/article1, src2023_12/cely, src2024_08/*, src2026_02, src2026_06/a08. + +References +---------- +Complete citations for the source tags used in this module (SPWLA journal +*Petrophysics*): + +src2021_02/article1 -- Article 1 (Tutorial): Maximizing Value From Mudlogs - Integrated Approach to + Determine Net Pay. Malik, Hanson, Clinch (2021). DOI: 10.30632/PJV62N1-2021t1. Petrophysics Vol. + 62 No. 1 (Feb 2021). +src2023_12/cely -- Cely et al. (2023), Petrophysics 64(6): 919-930. Reservoir oil viscosity + estimation in the Breidablikk Field from advanced mud-gas ratios + cuttings geochemistry, + compared against PVT. +src2024_08 -- Petrophysics Vol. 65 No. 4 (Aug 2024) — Special Issue on Advancements in Mud Logging + (issue-level reference). +src2026_02 -- Petrophysics Vol. 67 No. 1 (Feb 2026) — SPWLA 66th Annual Symposium best papers + (issue-level reference). +src2026_06/a08 -- Luo, P., Li, W., Lu, P., and Qubaisi, K. (2026). An Improved Mud Gas Ratio Method + for Enhanced Fluid Identification While Drilling. Petrophysics, 67(3), 582-593. DOI: + 10.30632/PJV67N3-2026a8. """ from __future__ import annotations diff --git a/petrolib/geochem_fluids/pvt.py b/petrolib/geochem_fluids/pvt.py index abdf426..2cee94f 100644 --- a/petrolib/geochem_fluids/pvt.py +++ b/petrolib/geochem_fluids/pvt.py @@ -7,6 +7,28 @@ Strict SI: pressures in Pa, temperature in K, molar mass in kg/mol, density in kg/m3. Sources: src2016_04/article4 (Wilson/Rachford-Rice/Peng-Robinson), src2019_08/article3 (Beggs-Brill), src2020_12/article6. + +References +---------- +Complete citations for the source tags used in this module (SPWLA journal +*Petrophysics*): + +src2016_04/article4 -- Article 4: A Multilevel Iterative Method to Quantify Effects of Pore-Size + Distribution on Phase Equilibrium of Multicomponent Fluids in Unconventional Plays. Li, + Mezzatesta, Li, Ma, Jamili (2016). Petrophysics Vol. 57, No. 2 (April 2016), pp. 121-139. DOI: + none assigned (this issue predates SPWLA DOI assignment). +src2017_06/article2_tgip_nmr_gas_shale -- Article 2: A Novel Determination of Total Gas-In-Place + (TGIP) for Gas Shale From Magnetic Resonance Logs. Kausik, Kleinberg, Rylander, Lewis, Sibbit, + Westacott (2017). Petrophysics Vol. 58, No. 3 (June 2017), pp. 232-241. DOI: none assigned (this + issue predates SPWLA DOI assignment). +src2019_08/article3 -- Article 3: The Compressibility Factor (Z) of Shale Gas at the Core Scale. + Tran, Sakhaee-Pour (2019). DOI: 10.30632/PJV60N4-2019a3. Petrophysics Vol. 60 No. 4 (Aug 2019). +src2019_08/article3_shale_gas_z_factor -- Article 3: The Compressibility Factor (Z) of Shale Gas at + the Core Scale. Tran, Sakhaee-Pour (2019). DOI: 10.30632/PJV60N4-2019a3. Petrophysics Vol. 60 No. + 4 (Aug 2019). +src2020_12/article6 -- Article 6: Maximizing the Value of Pulsed-Neutron Logs - A Complex Case + Study of Gas Pressure Assessment Through Casing. Cavalleri, Brouwer, Kodri, Rose, Brinks (2020). + DOI: 10.30632/PJV61N6-2020a6. Petrophysics Vol. 61 No. 6 (Dec 2020). """ from __future__ import annotations @@ -24,14 +46,20 @@ def pseudo_reduced( p: ArrayLike, t: ArrayLike, ppc: ArrayLike, tpc: ArrayLike ) -> tuple[_Float, _Float]: - """Pseudo-reduced pressure and temperature ``(P/Ppc, T/Tpc)``.""" + """Pseudo-reduced pressure and temperature ``(P/Ppc, T/Tpc)``. + + Sources: src2019_08/article3_shale_gas_z_factor. + """ ppr = np.asarray(p, np.float64) / np.asarray(ppc, np.float64) tpr = np.asarray(t, np.float64) / np.asarray(tpc, np.float64) return np.asarray(ppr), np.asarray(tpr) def z_beggs_brill(ppr: ArrayLike, tpr: ArrayLike) -> _Float: - """Beggs-Brill (1973) gas compressibility factor from pseudo-reduced P/T.""" + """Beggs-Brill (1973) gas compressibility factor from pseudo-reduced P/T. + + Sources: src2019_08/article3_shale_gas_z_factor. + """ ppr_a = np.asarray(ppr, np.float64) tpr_a = np.asarray(tpr, np.float64) a = 1.39 * (tpr_a - 0.92) ** 0.5 - 0.36 * tpr_a - 0.101 @@ -80,7 +108,10 @@ def z_peng_robinson( def gas_density( p_pa: ArrayLike, t_k: ArrayLike, *, m_kg_mol: ArrayLike = MW_METHANE, z: ArrayLike = 1.0 ) -> _Float: - """Real-gas density ``rho = P*M/(z*R*T)`` (kg/m3).""" + """Real-gas density ``rho = P*M/(z*R*T)`` (kg/m3). + + Sources: src2019_08/article3_shale_gas_z_factor. + """ return np.asarray( np.asarray(p_pa, np.float64) * np.asarray(m_kg_mol, np.float64) @@ -102,7 +133,10 @@ def pressure_from_gas_density( def mixture_mw(y: ArrayLike, mw: ArrayLike, *, axis: int = -1) -> _Float: - """Mixture molecular weight ``sum(y_i*MW_i)`` over ``axis``.""" + """Mixture molecular weight ``sum(y_i*MW_i)`` over ``axis``. + + Sources: src2017_06/article2_tgip_nmr_gas_shale. + """ return np.asarray(np.sum(np.asarray(y, np.float64) * np.asarray(mw, np.float64), axis=axis)) diff --git a/petrolib/geochem_fluids/solubility.py b/petrolib/geochem_fluids/solubility.py index 87ce937..c4076b9 100644 --- a/petrolib/geochem_fluids/solubility.py +++ b/petrolib/geochem_fluids/solubility.py @@ -7,6 +7,29 @@ Units: pressure in MPa, temperature in K, salinity as NaCl molality (mol/kg), solubility in mol/kg. Sources: src2022_04/article5, src2023_12/wang, src2026_02/co2_sequestration. + +References +---------- +Complete citations for the source tags used in this module (SPWLA journal +*Petrophysics*): + +src2022_04/article5 -- Article 5: Experimental Investigation on the Effect of Methane Solubility in + Oil-Based Mud Under Downhole Conditions. Song, Sukari, Wang, Jiang, Cai, Xu, Huang (2022). DOI: + 10.30632/PJV63N2-2022a5. Petrophysics Vol. 63 No. 2 (Apr 2022). +src2022_04/article5_methane_solubility_obm -- Article 5: Experimental Investigation on the Effect + of Methane Solubility in Oil-Based Mud Under Downhole Conditions. Song, Sukari, Wang, Jiang, Cai, + Xu, Huang (2022). DOI: 10.30632/PJV63N2-2022a5. Petrophysics Vol. 63 No. 2 (Apr 2022). +src2023_12/wang -- Wang and Ehlig-Economides (2023), Petrophysics 64(6): 970-977. CO2 solubility in + saline water for CO2 trapping, accounting for pressure, temperature, salinity, and an often- + neglected factor (e.g., dissolved CH4 or the activity-coefficient correction). Implements a Duan- + Sun-style solubility model in simplified form. +src2023_12/wang_co2_solubility -- Wang and Ehlig-Economides (2023), Petrophysics 64(6): 970-977. + CO2 solubility in saline water for CO2 trapping, accounting for pressure, temperature, salinity, + and an often-neglected factor (e.g., dissolved CH4 or the activity-coefficient correction). + Implements a Duan-Sun-style solubility model in simplified form. +src2026_02/co2_sequestration -- Article 8: Effect of CO2 Sequestration on Carbonate Formation + Integrity - Aspects of Static Interactions. Al-Hamad et al. (2026), Petrophysics, 67(1), 106-122. + DOI: 10.30632/PJV67N1-2026a8. """ from __future__ import annotations @@ -23,6 +46,8 @@ def henry_constant_co2(t_k: ArrayLike) -> _Float: """CO2 Henry constant (MPa/molality), Duan-Sun style vs temperature (K). ``H = 10*exp(-9.4234 + 4.0087e-2*T - 4.5e-5*T**2)``. + + Sources: src2023_12/wang_co2_solubility. """ t = np.asarray(t_k, np.float64) return np.asarray(10.0 * np.exp(-9.4234 + 4.0087e-2 * t - 4.5e-5 * t**2)) @@ -44,6 +69,8 @@ def co2_solubility_brine( ``H`` from :func:`henry_constant_co2`, ``gamma`` from :func:`setschenow_factor`; ``m_ch4`` accounts for methane competition. + + Sources: src2023_12/wang_co2_solubility. """ h = henry_constant_co2(t_k) gamma = setschenow_factor(m_nacl, t_k) @@ -54,7 +81,10 @@ def co2_solubility_brine( def henry_solubility_ln( p_mpa: ArrayLike, t_k: ArrayLike, a: ArrayLike, b: ArrayLike, dh_j_mol: ArrayLike ) -> _Float: - """Krichevsky-Kasarnovsky ``ln(x) = a + b*ln(P) - dH/(R*T)`` (gas-in-oil mole fraction).""" + """Krichevsky-Kasarnovsky ``ln(x) = a + b*ln(P) - dH/(R*T)`` (gas-in-oil mole fraction). + + Sources: src2022_04/article5_methane_solubility_obm. + """ return np.asarray( np.asarray(a, np.float64) + np.asarray(b, np.float64) * np.log(np.asarray(p_mpa, np.float64)) diff --git a/petrolib/integrity_drilling.py b/petrolib/integrity_drilling.py index 25a7c28..b5e062d 100644 --- a/petrolib/integrity_drilling.py +++ b/petrolib/integrity_drilling.py @@ -24,6 +24,82 @@ SI in/out unless a suffix says otherwise (``*_psi``, ``*_bar``); acoustic impedance is in MRayl; keyword defaults are the most common values observed in the articles. + +References +---------- +Complete citations for the source tags used in this module (SPWLA journal +*Petrophysics*): + +src2014_04/article1_deepwater_gom_overview -- Article 1: Deepwater Exploration and Production in + the Gulf of Mexico - Challenges and Opportunities. Hani Elshahawi (2014). Petrophysics Vol. 55, + No. 2 (April 2014), pp. 81-87. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2014_04/article5_deepwater_formation_evaluation -- Article 5: Formation-Evaluation Challenges + and Opportunities in Deepwater Roland Chemali, Wade Samec, Ron Balliet, Paul Cooper, David + Torres, Chris Jones (2014). Petrophysics Vol. 55, No. 2 (April 2014), pp. 124-135. DOI: none + assigned (this issue predates SPWLA DOI assignment). +src2019_02/article5_composite_cement_well_integrity -- Article 5: Novel Composite Cement for + Improved Well Integrity Evaluation. Elshahawi, Huang, Pollock, Veedu (2019). DOI: + 10.30632/PJV60N1Y2019a4. Petrophysics Vol. 60 No. 1 (Feb 2019). +src2019_10/article6_microct_invasion_mudcake -- Article 6: Experimental Method for Time-Lapse + Micro-CT Imaging of Mud-Filtrate Invasion and Mudcake Deposition. Schroeder, Torres-Verdin + (2019). DOI: 10.30632/PJV60N5-2019a6. Petrophysics Vol. 60 No. 5 (Oct 2019). +src2020_08/article1_flexural_attenuation_casing -- Article 1: A Study of the Flexural Attenuation + Technique Through Laboratory Measurements and Numerical Simulations. Sirevaag, Johansen, Larsen, + Holt (2020). DOI: 10.30632/PJV61N4-2020a1. Petrophysics Vol. 61 No. 4 (Aug 2020). +src2021_02/article1_mudlog_net_pay_tutorial -- Article 1 (Tutorial): Maximizing Value From Mudlogs + - Integrated Approach to Determine Net Pay. Malik, Hanson, Clinch (2021). DOI: + 10.30632/PJV62N1-2021t1. Petrophysics Vol. 62 No. 1 (Feb 2021). +src2021_12/article07_multistring_isolation_acoustic -- Article 7: Case Studies on Multistring + Isolation Evaluation in P&A Operations. Zhang, Mueller, Bryce, Brockway, Iskander (2021). DOI: + 10.30632/PJV62N6-2021a7. Petrophysics Vol. 62 No. 6 (Dec 2021). +src2021_12/article08_overbalanced_drilling_correction -- Article 8: The Impact of Overbalanced + Drilling From Exploration/Appraisal Wells to Field Development Plan. Mohammadlou, Reppert, Del + Negro, Jones (2021). DOI: 10.30632/PJV62N6-2021a8. Petrophysics Vol. 62 No. 6 (Dec 2021). +src2022_02/article4_ultrasonic_creeping_shale -- Article 4: Ultrasonic Logging of Creeping Shale. + Diez, Johansen, Larsen (2022). DOI: 10.30632/PJV63N1-2022a4. Petrophysics Vol. 63 No. 1 (Feb + 2022). +src2022_04/article4_microct_filtercake -- Article 4: In-Situ Visualization and Characterization of + Filter-Cake Deposition Using Time-Lapse Micro-CT Imaging. Schroeder, Torres-Verdin (2022). DOI: + 10.30632/PJV63N2-2022a4. Petrophysics Vol. 63 No. 2 (Apr 2022). +src2022_10/article5_cement_acid_gas_corrosion -- Article 5: Corrosion Behavior and Mechanism + Analysis of Oilwell Cement Under CO2 and H2S Conditions. Zhou, Zeng, Sun, Zhou, Lei, Wan, Luo, + Wu, Zhang, Xiao (2022). DOI: 10.30632/PJV63N5-2022a5. Petrophysics Vol. 63 No. 5 (Oct 2022). +src2023_08/article2_invasion_simulation -- Implements the rock/fluid/mudcake equations and the + radial 1-D mud-filtrate invasion + Archie-resistivity workflow described in: Merletti, G., Al + Hajri, S., Rabinovich, M., Farmer, R., Bennis, M., Torres-Verdín, C. (2023). "Assessment of True + Formation Resistivity and Water Saturation in Deeply Invaded Tight-Gas Sandstones Based on the + Combined Numerical Simulation of Mud-Filtrate Invasion and Resistivity Logs", Petrophysics, Vol. + 64, No. 4, pp. 502-517. DOI: 10.30632/PJV64N4-2023a2. +src2024_08/mudgas_response -- What Causes Mud-Logging Mud Gas Response to Vary and Two Techniques + to Quantify. Based on: Donovan, W.S. (2024), "What Causes Mud-Logging Mud Gas Response to Vary + and Two Techniques to Quantify Mud Gas," Petrophysics, 65(4), pp. 565-584. DOI: + 10.30632/PJV65N4-2024a10. +src2024_12/m04_well_integrity_ccs -- Well Integrity Measurements Throughout the CCS Project Life + Cycle. Based on: Valstar, Nettleton, Borchardt, Costeno, Landry, and Laronga (2024), Petrophysics + 65(6), pp. 896-912. DOI: 10.30632/PJV65N6-2024a4. +src2024_12/m05_casing_cement_inspection -- Casing and Cement Inspection: Logging Two Casing Sizes + Simultaneously. Based on: Hawthorn, Ingebretson, Girneata, Delabroy, Winther, Steinsiek, and + Leslie (2024), Petrophysics 65(6), pp. 913-918. DOI: 10.30632/PJV65N6-2024a5. +src2025_04/microannuli_leak_rate -- Advanced Ultrasonic Log Analysis and Mechanistic Modeling for + Leak Rate Quantification Through Microannuli. Based on: Machicote et al., "The Road Through + Microannuli: Advanced Ultrasonic Log Analysis and Mechanistic Modeling for Leak Rate + Quantification", Petrophysics, Vol. 66, No. 2, April 2025, pp. 331–347. +src2025_04/overpressure_isotope -- Genetic Analysis of Overpressure While Drilling Based on Isotope + Logging. Based on: Hu et al., "Genetic Analysis of Overpressure While Drilling Based on Isotope + Logging Technology", Petrophysics, Vol. 66, No. 2, April 2025, pp. 283–293. +src2025_08/cement_snhr_emi -- Module 10: Through-Tubing Cement Evaluation (SNHR + EMI + ML) + Implements ideas from: Zeghlache et al., "Challenges and Solutions for Advanced Through- Tubing + Cement Evaluation," Petrophysics, vol. 66, no. 4, pp. 677–688, August 2025. +src2025_08/seven_pipe_em_corrosion -- Module 3: Seven-Pipe Electromagnetic Corrosion Evaluation + Implements ideas from: Fouda et al., "First-Ever Seven-Pipe Corrosion Evaluation for + Comprehensive Assessment of Pipe Integrity in Complex Well Completions," Petrophysics, vol. 66, + no. 4, pp. 566–577, August 2025. +src2026_04/a11_awi_cement_evaluation -- Zhang, X., Zhang, X., Zhang, T., Li, X., Mei, C., Li, B., + Jiang, M., Liu, K., and Bai, Y. (2026). New Equipment and Method for Evaluating Anti-Water- + Invasion Ability of Cement Slurry. Petrophysics, 67(2), 421–435. DOI: 10.30632/PJV67N2-2026a11. +src2026_06/a08_mud_gas_ratio_fluid_id -- Luo, P., Li, W., Lu, P., and Qubaisi, K. (2026). An + Improved Mud Gas Ratio Method for Enhanced Fluid Identification While Drilling. Petrophysics, + 67(3), 582-593. DOI: 10.30632/PJV67N3-2026a8. """ from __future__ import annotations @@ -59,6 +135,8 @@ def acoustic_impedance(rho: ArrayLike, v: ArrayLike, *, rho_unit: str = "kg/m3") ``rho_unit='kg/m3'`` takes SI density; ``'g/cc'`` takes g/cm^3 (the CBL articles' convention, ``Z = rho_gcc * v / 1000``). + + Sources: src2019_02/article5_composite_cement_well_integrity. """ if rho_unit == "kg/m3": return acoustic_geomech.acoustic_impedance(rho, v, out="mrayl") @@ -78,7 +156,10 @@ def transmission_energy(z1: ArrayLike, z2: ArrayLike) -> _Float: def attenuation_db(a_near: ArrayLike, a_far: ArrayLike, spacing_m: float | None = None) -> _Float: - """Amplitude attenuation ``20*log10(A_near/A_far)`` in dB (dB/m if ``spacing_m`` given).""" + """Amplitude attenuation ``20*log10(A_near/A_far)`` in dB (dB/m if ``spacing_m`` given). + + Sources: src2020_08/article1_flexural_attenuation_casing. + """ db = 20.0 * np.log10(_arr(a_near) / _arr(a_far)) if spacing_m is not None: db = db / spacing_m @@ -86,7 +167,10 @@ def attenuation_db(a_near: ArrayLike, a_far: ArrayLike, spacing_m: float | None def attenuation_coefficient(a0: ArrayLike, ax: ArrayLike, x_m: ArrayLike) -> _Float: - """Exponential attenuation coefficient ``ln(A0/Ax)/x`` (1/m) from ``A = A0*exp(-alpha*x)``.""" + """Exponential attenuation coefficient ``ln(A0/Ax)/x`` (1/m) from ``A = A0*exp(-alpha*x)``. + + Sources: src2020_08/article1_flexural_attenuation_casing. + """ return acoustic_geomech.attenuation_coefficient(a0, ax, x_m) @@ -108,6 +192,9 @@ def bond_index( free_pipe)``. ``method='log'`` (amplitude only) uses the logarithmic CBL convention ``BI = log(free_pipe/A) / log(free_pipe/well_bonded)`` with 0.01 floors on the amplitudes. The result is clipped to ``clip``. + + Sources: src2019_02/article5_composite_cement_well_integrity, + src2025_04/microannuli_leak_rate. """ m = _arr(measured) if method == "linear": @@ -142,6 +229,8 @@ def bond_index_combined( ``corrector`` (optional callable) maps the raw combination to a corrected value before clipping -- e.g. an eccentricity-correction model. + + Sources: src2025_08/cement_snhr_emi. """ combined = weights[0] * _arr(bi_a) + weights[1] * _arr(bi_b) if corrector is not None: @@ -157,6 +246,9 @@ def classify_annulus( ``'gas'`` below ``gas_max``, ``'liquid'`` below ``liquid_max``, ``'cement'`` at or above ``cement_min``, else ``'transition'``. Pass ``cement_min=liquid_max`` to remove the transition band. + + Sources: src2019_02/article5_composite_cement_well_integrity, + src2021_12/article07_multistring_isolation_acoustic. """ if z_mrayl < gas_max: return "gas" @@ -186,6 +278,8 @@ def cement_quality_score( Above the ``good`` threshold the score is 1; between ``fair`` and ``good`` it ramps 0.5..1; below ``fair`` it ramps toward 0. Thresholds default per ``cement_type`` (:data:`CEMENT_QUALITY_THRESHOLDS`). + + Sources: src2024_12/m04_well_integrity_ccs. """ imp = _arr(z_mrayl) good, fair = ( @@ -224,6 +318,9 @@ def casing_resonance_frequency( ``correction`` absorbs mode corrections (e.g. 0.95 for the S1 negative-group-velocity minimum). + + Sources: src2021_12/article07_multistring_isolation_acoustic, + src2022_02/article4_ultrasonic_creeping_shale. """ return np.asarray(correction * n * v / (2.0 * _arr(thickness_m))) @@ -236,7 +333,10 @@ def casing_thickness_from_resonance( def metal_loss_pct(measured: ArrayLike, nominal: ArrayLike) -> _Float: - """Casing metal loss ``(1 - measured/nominal)*100``, clipped to [0, 100] %.""" + """Casing metal loss ``(1 - measured/nominal)*100``, clipped to [0, 100] %. + + Sources: src2025_08/seven_pipe_em_corrosion. + """ return np.asarray(np.clip((1.0 - _arr(measured) / _arr(nominal)) * 100.0, 0, 100)) @@ -246,6 +346,8 @@ def casing_condition( """Casing condition class from metal loss %: good / fair / poor / critical. Strict ``<`` at each band edge, matching the corpus convention. + + Sources: src2024_12/m05_casing_cement_inspection. """ loss = _arr(loss_pct) return np.asarray( @@ -270,7 +372,10 @@ def remaining_life_years( def corrosion_front_depth(t: ArrayLike, K: float = 2.5) -> _Float: - """Diffusion-limited corrosion front ``x = K*sqrt(t)`` (units follow ``K``).""" + """Diffusion-limited corrosion front ``x = K*sqrt(t)`` (units follow ``K``). + + Sources: src2022_10/article5_cement_acid_gas_corrosion. + """ return np.asarray(K * np.sqrt(np.maximum(_arr(t), 0.0))) @@ -283,6 +388,8 @@ def microannulus_omega(r_casing_m: float, aperture_m: float) -> float: For the gap between ``R1 = r_casing_m`` and ``R2 = R1 + aperture``: ``Omega = R2^4 - R1^4 - (R2^2 - R1^2)^2 / ln(R2/R1)``; zero for a closed (non-positive) aperture. + + Sources: src2025_04/microannuli_leak_rate. """ if aperture_m <= 0: return 0.0 @@ -309,6 +416,8 @@ def leak_rate_liquid( ``Q = (pi / (8 mu L)) * Omega * (dP - rho g L cos(theta))`` with ``theta`` the well inclination from horizontal (90 deg = vertical). Returns 0 when the applied pressure cannot overcome gravity (or the gap is closed). + + Sources: src2025_04/microannuli_leak_rate. """ if aperture_m <= 0 or length_m <= 0: return 0.0 @@ -333,6 +442,8 @@ def leak_rate_gas( """Gas microannulus leak rate (m^3/s at outlet), isothermal compressible flow. ``Q = (pi / (16 mu L P2)) * Omega * (P1^2 - P2^2)``; gravity neglected. + + Sources: src2025_04/microannuli_leak_rate. """ if aperture_m <= 0 or length_m <= 0 or p_out_pa <= 0: return 0.0 @@ -344,7 +455,10 @@ def leak_rate_gas( def cubic_law_conductivity( aperture_m: ArrayLike, *, rho: float = 1000.0, mu: float = 1e-3, g: float = 9.81 ) -> _Float: - """Parallel-plate crack hydraulic conductivity ``K = rho g w^3 / (12 mu)`` (m/s).""" + """Parallel-plate crack hydraulic conductivity ``K = rho g w^3 / (12 mu)`` (m/s). + + Sources: src2026_04/a11_awi_cement_evaluation. + """ return np.asarray(rho * g * _arr(aperture_m) ** 3 / (12.0 * mu)) @@ -359,6 +473,8 @@ def haworth_ratios( ``Wh = (C2+..+C5)/total`` (x100 if ``percent``), ``Bh = (C1+C2)/(C3+C4+C5)``, ``Ch = (C4+C5)/C3``. Any consistent gas units. Empty gas returns NaN wetness; zero denominators return +inf. + + Sources: src2026_06/a08_mud_gas_ratio_fluid_id. """ total = c1 + c2 + c3 + c4 + c5 if total <= 0.0: @@ -375,6 +491,8 @@ def pixler_ratios(c1: float, c2: float, c3: float, c4: float, c5: float) -> dict """Pixler component ratios ``C1/C2 .. C1/C5`` plus the Bernard ratio ``C1/(C2+C3)``. Zero denominators return +inf. + + Sources: src2021_02/article1_mudlog_net_pay_tutorial. """ c1f = float(c1) out: dict[str, float] = {} @@ -394,6 +512,9 @@ def classify_fluid_haworth( ``n_classes=4`` uses the classic bands (dry gas < 0.5 %, gas / gas-condensate < 17.5 % split on ``bh > wh``, oil < 40 %, else residual oil). ``n_classes=8`` uses the extended 2026 scheme (requires ``ch``). + + Sources: src2021_02/article1_mudlog_net_pay_tutorial, + src2026_06/a08_mud_gas_ratio_fluid_id. """ if n_classes == 4: if wh < 0.5: @@ -439,6 +560,8 @@ def normalize_gas( divides the reading by the ratio-to-``reference`` factors ``(ROP/ROP0)*(Q/Q0)*(MW/MW0)^2`` (ft/hr, gpm, ppg; ``bit_diameter`` unused) to bring it to reference conditions. + + Sources: src2021_02/article1_mudlog_net_pay_tutorial, src2024_08/mudgas_response. """ if units == "metric": area = np.pi * (_arr(bit_diameter) * 0.0254 / 2.0) ** 2 @@ -464,12 +587,18 @@ def hydrostatic_pressure(tvd_m: ArrayLike, *, rho: float = 1030.0) -> _Float: def hydrostatic_pressure_psi(tvd_ft: ArrayLike, *, sg: float = 1.0) -> _Float: - """Hydrostatic pressure in psi from TVD in ft: ``0.433 * SG * TVD``.""" + """Hydrostatic pressure in psi from TVD in ft: ``0.433 * SG * TVD``. + + Sources: src2014_04/article1_deepwater_gom_overview. + """ return np.asarray(PSI_PER_FT_PER_SG * sg * _arr(tvd_ft)) def hydrostatic_pressure_bar(tvd_m: ArrayLike, *, sg: float = 1.0) -> _Float: - """Hydrostatic pressure in bar from TVD in m: ``0.0980665 * SG * TVD``.""" + """Hydrostatic pressure in bar from TVD in m: ``0.0980665 * SG * TVD``. + + Sources: src2021_12/article08_overbalanced_drilling_correction. + """ return np.asarray(BAR_PER_SG_M * sg * _arr(tvd_m)) @@ -491,7 +620,10 @@ def overburden_pressure_psi( sw_sg: float = 1.025, sediment_sg: float = 2.3, ) -> _Float: - """Deepwater overburden in psi: ``0.433 * (SG_sw*wd + SG_sed*sd)``.""" + """Deepwater overburden in psi: ``0.433 * (SG_sw*wd + SG_sed*sd)``. + + Sources: src2014_04/article1_deepwater_gom_overview. + """ return np.asarray( PSI_PER_FT_PER_SG * (sw_sg * _arr(water_depth_ft) + sediment_sg * _arr(sediment_depth_ft)) ) @@ -514,6 +646,9 @@ def eaton_pore_pressure( uses ``ratio = observed/normal``. Works in pressure or gradient space (the output follows the input units). ``clip_ratio`` optionally bounds the ratio (e.g. ``(0.01, 100.0)``). + + Sources: src2014_04/article5_deepwater_formation_evaluation, + src2025_04/overpressure_isotope. """ ob = _arr(overburden) hyd = _arr(hydrostatic) @@ -545,6 +680,8 @@ def bowers_pore_pressure( (floored at 0.01) and subtracts it from the overburden; ``unloading=True`` uses the flatter unloading branch with maximum stress ``sigma_max`` and exponent ``U``. + + Sources: src2025_04/overpressure_isotope. """ v = _arr(velocity) ob = _arr(overburden) @@ -556,12 +693,18 @@ def bowers_pore_pressure( def drilling_window_margin(pore: ArrayLike, frac: ArrayLike) -> _Float: - """Drilling-window width ``frac - pore`` (same units as the inputs).""" + """Drilling-window width ``frac - pore`` (same units as the inputs). + + Sources: src2014_04/article5_deepwater_formation_evaluation. + """ return np.asarray(_arr(frac) - _arr(pore)) def within_drilling_window(ecd: float, pore: float, frac: float) -> bool: - """True when the ECD sits strictly inside the pore/frac window.""" + """True when the ECD sits strictly inside the pore/frac window. + + Sources: src2014_04/article5_deepwater_formation_evaluation. + """ return bool(pore < ecd < frac) @@ -587,6 +730,9 @@ def mudcake_thickness( ``model='chin_ode'`` integrates the Chin thickness ODE with a pressure-decaying cake permeability ``K(t) = k_mc * ((t + 1e-3)/1e-3)^-v`` (10-micron seed cake, ``solids_ratio`` is the mud solid fraction ``fs``). + + Sources: src2019_10/article6_microct_invasion_mudcake, + src2022_04/article4_microct_filtercake, src2023_08/article2_invasion_simulation. """ t = _arr(t_s) if model == "sqrt_k": diff --git a/petrolib/inversion_numerics/costs.py b/petrolib/inversion_numerics/costs.py index 6fe8e61..1025f51 100644 --- a/petrolib/inversion_numerics/costs.py +++ b/petrolib/inversion_numerics/costs.py @@ -3,6 +3,27 @@ Data-misfit measures (L2, RMS, relative, chi-square) and the two regularization schedules the corpus uses: Habashy-Abubakar multiplicative cooling and the discrepancy-principle (BRD) bisection. + +References +---------- +Complete citations for the source tags used in this module (SPWLA journal +*Petrophysics*): + +src2014_10/article1_lwd_inversion_anisotropy -- Article 1: Inversion-Based Interpretation of + Logging-While-Drilling Resistivity and Nuclear Measurements: Field Examples in High-Angle and + Horizontal Wells Olabode Ijasan, Carlos Torres-Verdin, William E. Preeg, John Rasmus, Edward J. + Stockhausen (2014). Petrophysics Vol. 55, No. 5 (October 2014), pp. 374-391. DOI: none assigned + (this issue predates SPWLA DOI assignment). +src2014_12/article2_obm_imager_inversion -- Article 2: Inversion-Based Workflow for Quantitative + Interpretation of the New-Generation Oil-Based-Mud Resistivity Imager Yong-Hua Chen, Dzevat + Omeragic, Tarek Habashy, Richard Bloemenkamp, Tianhua Zhang, Phillip Cheung, Robert Laronga + (2014). Petrophysics Vol. 55, No. 6 (December 2014), pp. 554-571. DOI: none assigned (this issue + predates SPWLA DOI assignment). +src2017_10/article4_joint_inversion_nearwellbore -- Article 4: Imaging Near-Wellbore Petrophysical + Properties by Joint Inversion of Sonic, Resistivity, and Density Logging Data. Shetty, Liang, + Simoes, Canesin, Boyd, Zeroug, Sinha, Habashy, Domingues, Amorim, Abbots (2017). Petrophysics + Vol. 58, No. 5 (October 2017), pp. 501-516. DOI: none assigned (this issue predates SPWLA DOI + assignment). """ from __future__ import annotations @@ -37,6 +58,9 @@ def misfit( * ``'chi2'`` -- ``sum(w*(sim-obs)^2)`` with ``w = 1/sigma^2`` ``log_space=True`` compares ``log10`` of the values first. + + Sources: src2014_10/article1_lwd_inversion_anisotropy, + src2017_10/article4_joint_inversion_nearwellbore. """ s = _arr(sim) o = _arr(obs) @@ -61,7 +85,10 @@ def misfit( def reg_lambda_multiplicative( misfit_value: float, alpha: float, beta: float, lam_max: float = np.inf ) -> float: - """Habashy-Abubakar multiplicative cooling ``lam = min(alpha*misfit^beta, lam_max)``.""" + """Habashy-Abubakar multiplicative cooling ``lam = min(alpha*misfit^beta, lam_max)``. + + Sources: src2014_12/article2_obm_imager_inversion. + """ return float(min(alpha * misfit_value**beta, lam_max)) diff --git a/petrolib/inversion_numerics/fitting.py b/petrolib/inversion_numerics/fitting.py index 2b53f25..5b3610f 100644 --- a/petrolib/inversion_numerics/fitting.py +++ b/petrolib/inversion_numerics/fitting.py @@ -4,6 +4,45 @@ returning slope/intercept/R^2, power-law-decay and exponential-relaxation fits, and the azimuthal cosine-harmonic fit. scipy (``curve_fit``) is imported lazily only where a nonlinear fit is genuinely needed. + +References +---------- +Complete citations for the source tags used in this module (SPWLA journal +*Petrophysics*): + +src2014_02/article3_nanofluid_imbibition -- Article 3: An Evaluation of Spontaneous Imbibition of + Water into Oil-Wet Carbonate Reservoir Cores Using Nanofluid. Abbas Roustaei (2014). Petrophysics + Vol. 55, No. 1 (February 2014), pp. 31-37. DOI: none assigned (this issue predates SPWLA DOI + assignment). +src2014_02/article4_canister_gas_isotopes -- Article 4: Desorbed Canister Gas Sampling and Gas + Isotopic Analysis Procedures and Practices: A Case Study of Two Coalbed Methane Wells from the + Lower Saxony Basin, Germany. Russell W. Spears, Sascha Alles, Alexey Makhonin (2014). + Petrophysics Vol. 55, No. 1 (February 2014), pp. 38-50. DOI: none assigned (this issue predates + SPWLA DOI assignment). +src2014_08/article3_microct_haines_jumps -- Article 3: Multiphase Flow in Porous Rock Imaged Under + Dynamic Flow Conditions with Fast X-Ray Computed Microtomography S. Berg, R. Armstrong, H. Ott, + A. Georgiadis, S. A. Klapp, A. Schwing, R. Neiteler, N. Brussee, A. Makurat, L. Leu, F. Enzmann, + J.-O. Schwarz, M. Wolf, F. Khan, M. Kersten, S. Irvine, M. Stampanoni (2014). Petrophysics Vol. + 55, No. 4 (August 2014), pp. 304-312. DOI: none assigned (this issue predates SPWLA DOI + assignment). +src2015_02/article1_oil_mobilization_clusters -- Article 1: Onset of Oil Mobilization and + Nonwetting-Phase Cluster-Size Distribution. Berg, Armstrong, Georgiadis, Ott, Schwing, Neiteler, + Brussee, Makurat, Rucker, Leu, Wolf, Khan, Enzmann, Kersten (2015). Petrophysics Vol. 56, No. 1 + (February 2015), pp. 15-22. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2015_02/article2_co2_diffusive_mixing -- Article 2: CO2 EOR by Diffusive Mixing in Fractured + Reservoirs. Eide, Ersland, Brattekas, Haugen, Graue, Ferno (2015). Petrophysics Vol. 56, No. 1 + (February 2015), pp. 23-31. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2015_04/article1_pressure_test_quality -- Article 1: Automatically Quantifying Wireline and LWD + Pressure-Test Quality. Proett, Musharfi, Gill, Ma, Meridji, Eyuboglu (2015). Petrophysics Vol. + 56, No. 2 (April 2015), pp. 101-115. DOI: none assigned (this issue predates SPWLA DOI + assignment). +src2015_04/article4_microresistivity_extraction -- Article 4: Microresistivity Curve Extraction + from Borehole Microimager Data. Roslin (2015). Petrophysics Vol. 56, No. 2 (April 2015), pp. + 140-146. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2015_06/article2_fluid_contamination_prediction -- Article 2: A Breakthrough in Accurate + Downhole Fluid Sample Contamination Prediction in Real Time. Zuo, Gisolf, Dumont, Dubost, + Pfeiffer, Wang, Mishra, Chen, Mullins, Biagi, Gemelli (2015). Petrophysics Vol. 56, No. 3 (June + 2015), pp. 251-265. DOI: none assigned (this issue predates SPWLA DOI assignment). """ from __future__ import annotations @@ -56,6 +95,12 @@ def fit_line( ``xform`` / ``yform`` optionally transform the axes first (e.g. ``'log10'`` for a log-log or semilog fit); slope/intercept/R^2 are reported in that transformed space. + + Sources: src2014_02/article3_nanofluid_imbibition, + src2014_02/article4_canister_gas_isotopes, src2014_08/article3_microct_haines_jumps, + src2015_02/article1_oil_mobilization_clusters, src2015_02/article2_co2_diffusive_mixing, + src2015_04/article1_pressure_test_quality, src2015_04/article4_microresistivity_extraction, + src2015_06/article2_fluid_contamination_prediction, and 33 more articles. """ xt = _transform(xform, _arr(x)) yt = _transform(yform, _arr(y)) diff --git a/petrolib/inversion_numerics/linear.py b/petrolib/inversion_numerics/linear.py index 04e42cd..90b4412 100644 --- a/petrolib/inversion_numerics/linear.py +++ b/petrolib/inversion_numerics/linear.py @@ -8,6 +8,46 @@ ``lam`` (regularization weight) is applied **once** everywhere -- never squared. scipy is imported lazily inside the functions that need it (NNLS). + +References +---------- +Complete citations for the source tags used in this module (SPWLA journal +*Petrophysics*): + +src2014_06/article4_nmr_carbonate_permeability -- Article 4: Method for Predicting Permeability of + Complex Carbonate Reservoirs Using NMR Logging Measurements Willian Trevizan, Paulo Neto, + Bernardo Coutinho, Vinicius F. Machado, Edmilson H. Rios, Songhua Chen, Wei Shao, Pedro Romero + (2014). Petrophysics Vol. 55, No. 3 (June 2014), pp. 240-252. DOI: none assigned (this issue + predates SPWLA DOI assignment). +src2015_04/article5_nmr_short_t2_porosity -- Article 5: New Method to Estimate Porosity More + Accurately from NMR Data with Short Relaxation Times. Venkataramanan, Gruber, LaVigne, Habashy, + Iglesias, Cohorn, Anand, Rampurawala, Jain, Heaton, Akkurt, Rylander, Lewis (2015). Petrophysics + Vol. 56, No. 2 (April 2015), pp. 147-157. DOI: none assigned (this issue predates SPWLA DOI + assignment). +src2015_08/article4_spectroscopy_inversion -- Article 4: Petrophysical Interpretation of LWD, + Neutron-Induced Gamma-Ray Spectroscopy Measurements: An Inversion-Based Approach. Ajayi, Torres- + Verdin, Preeg (2015). Petrophysics Vol. 56, No. 4 (August 2015), pp. 358-378. DOI: none assigned + (this issue predates SPWLA DOI assignment). +src2017_06/article3_forward_mineral_svd -- Article 3: Forward Mineral Modeling Using Regularized + Least-Squares Regression With Singular Value Decomposition: Case Study From Qusaiba Shale. Xu, + McCormick, Herron, Cheshire, Al-Salim, Almarzouq (2017). Petrophysics Vol. 58, No. 3 (June 2017), + pp. 242-269. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2019_06/article3_wellsite_tomography_bayesian -- Article 3: Accelerated Whole-Core Analysis + Optimization With Wellsite Tomography Instrumentation and Bayesian Inversion. Mendoza, Roininen, + Girolami, Heikkinen, Haario (2019). DOI: 10.30632/PJV60N3-2019a2. Petrophysics Vol. 60 No. 3 (Jun + 2019). +src2019_12/article1_sonic_inversion_deconvolution -- Article 1: Inversion of High-Resolution High- + Quality Sonic Compressional and Shear Logs for Unconventional Reservoirs. Lei, Zeroug, Bose, + Prioul, Donald (2019). DOI: 10.30632/PJV60N6-2019a1. Petrophysics Vol. 60 No. 6 (Dec 2019). +src2020_02/article4_physics_deeplearning_inversion -- Article 4: A Physics-Driven Deep-Learning + Network for Solving Nonlinear Inverse Problems. Jin, Shen, Wu, Chen, Huang (2020). DOI: + 10.30632/PJV61N1-2020a3. Petrophysics Vol. 61 No. 1 (Feb 2020). +src2021_02/article8_injectite_em_3d_inversion -- Article 8: Mapping Complex Injectite Bodies With + Multiwell Electromagnetic 3D Inversion Data. Clegg, Eriksen, Best, Tollefsen, Kowicki, Marchant + (2021). DOI: 10.30632/PJV62N1-2021a7. Petrophysics Vol. 62 No. 1 (Feb 2021). +src2026_02/nmr_discrete_inversion -- Article 3: Discrete Inversion Method for Nuclear Magnetic + Resonance Data Processing and Its Applications to Fluid Typing and Quantification. Gao et al. + (2026), Petrophysics, 67(1), 38-53. DOI: 10.30632/PJV67N1-2026a3. """ from __future__ import annotations @@ -40,7 +80,10 @@ def difference_operator(n: int, order: int = 1) -> _Float: def condition_number(a: ArrayLike) -> float: - """2-norm condition number ``s_max/s_min`` from the singular values.""" + """2-norm condition number ``s_max/s_min`` from the singular values. + + Sources: src2017_06/article3_forward_mineral_svd. + """ s = np.linalg.svd(_arr(a), compute_uv=False) return float(s[0] / s[-1]) @@ -71,6 +114,12 @@ def tikhonov_solve( ``argmin_x ||W(Ax - b)||^2 + lam*||L(x - x_ref)||^2`` with ``L = reg_op`` (identity by default), data weights ``W = diag(1/sigma)``, and ``lam`` applied **once**. ``nonneg=True`` solves the augmented system with :func:`nnls_solve`. + + Sources: src2014_06/article4_nmr_carbonate_permeability, + src2015_04/article5_nmr_short_t2_porosity, src2015_08/article4_spectroscopy_inversion, + src2017_06/article3_forward_mineral_svd, + src2020_02/article4_physics_deeplearning_inversion, + src2021_02/article8_injectite_em_3d_inversion, src2026_02/nmr_discrete_inversion. """ a_arr = _arr(a) b_arr = _arr(b) @@ -229,7 +278,11 @@ def convolution_matrix(kernel: ArrayLike, n: int) -> _Float: def deconvolve(d: ArrayLike, g: ArrayLike, rank: int | None = None) -> _Float: - """Deconvolve ``d = G x`` for ``x`` via (rank-limited) pseudo-inverse.""" + """Deconvolve ``d = G x`` for ``x`` via (rank-limited) pseudo-inverse. + + Sources: src2019_06/article3_wellsite_tomography_bayesian, + src2019_12/article1_sonic_inversion_deconvolution. + """ g_arr = _arr(g) d_arr = _arr(d) if rank is None: diff --git a/petrolib/inversion_numerics/nonlinear.py b/petrolib/inversion_numerics/nonlinear.py index d81d081..713a69f 100644 --- a/petrolib/inversion_numerics/nonlinear.py +++ b/petrolib/inversion_numerics/nonlinear.py @@ -4,6 +4,16 @@ Levenberg-Marquardt with box bounds and optional log-parameters, an Occam smoothest-model iteration, brute-force grid search, multistart, and feasible-set (equivalence) sampling for uncertainty bounds. + +References +---------- +Complete citations for the source tags used in this module (SPWLA journal +*Petrophysics*): + +src2016_10/article3_foep_error_propagation -- Article 3: On Error Calculation and Use of First- + Order Error Propagation as Integral Part of Petrophysical Calculation. Stalheim (2016). + Petrophysics Vol. 57, No. 5 (October 2016), pp. 465-478. DOI: none assigned (this issue predates + SPWLA DOI assignment). """ from __future__ import annotations @@ -62,7 +72,10 @@ def fd_jacobian( def fd_gradient(f: Callable[[_Float], float], x: ArrayLike, **kw: Any) -> _Float: - """Finite-difference gradient of a scalar objective ``f``.""" + """Finite-difference gradient of a scalar objective ``f``. + + Sources: src2016_10/article3_foep_error_propagation. + """ return fd_jacobian(lambda z: np.array([f(z)]), x, **kw).ravel() diff --git a/petrolib/ml_stats.py b/petrolib/ml_stats.py index 2279359..91b5f89 100644 --- a/petrolib/ml_stats.py +++ b/petrolib/ml_stats.py @@ -29,6 +29,118 @@ farthest-point init, not a random one). The single-hidden-layer NN trainers and non-farthest k-means inits found in some articles stay article-local until an adoption PR proves an exact-equivalence mapping. + +References +---------- +Complete citations for the source tags used in this module (SPWLA journal +*Petrophysics*): + +src2014_06/article4 -- Article 4: Method for Predicting Permeability of Complex Carbonate + Reservoirs Using NMR Logging Measurements Willian Trevizan, Paulo Neto, Bernardo Coutinho, + Vinicius F. Machado, Edmilson H. Rios, Songhua Chen, Wei Shao, Pedro Romero (2014). Petrophysics + Vol. 55, No. 3 (June 2014), pp. 240-252. DOI: none assigned (this issue predates SPWLA DOI + assignment). +src2014_08/article3 -- Article 3: Multiphase Flow in Porous Rock Imaged Under Dynamic Flow + Conditions with Fast X-Ray Computed Microtomography S. Berg, R. Armstrong, H. Ott, A. Georgiadis, + S. A. Klapp, A. Schwing, R. Neiteler, N. Brussee, A. Makurat, L. Leu, F. Enzmann, J.-O. Schwarz, + M. Wolf, F. Khan, M. Kersten, S. Irvine, M. Stampanoni (2014). Petrophysics Vol. 55, No. 4 + (August 2014), pp. 304-312. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2015_02/article1 -- Article 1: Onset of Oil Mobilization and Nonwetting-Phase Cluster-Size + Distribution. Berg, Armstrong, Georgiadis, Ott, Schwing, Neiteler, Brussee, Makurat, Rucker, Leu, + Wolf, Khan, Enzmann, Kersten (2015). Petrophysics Vol. 56, No. 1 (February 2015), pp. 15-22. DOI: + none assigned (this issue predates SPWLA DOI assignment). +src2015_04/article1 -- Article 1: Automatically Quantifying Wireline and LWD Pressure-Test Quality. + Proett, Musharfi, Gill, Ma, Meridji, Eyuboglu (2015). Petrophysics Vol. 56, No. 2 (April 2015), + pp. 101-115. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2015_04/article4 -- Article 4: Microresistivity Curve Extraction from Borehole Microimager Data. + Roslin (2015). Petrophysics Vol. 56, No. 2 (April 2015), pp. 140-146. DOI: none assigned (this + issue predates SPWLA DOI assignment). +src2015_10 -- Petrophysics Vol. 56 No. 5 (Oct 2015) (issue-level reference). +src2016_08/article2 -- Article 2: Predicting Carbonate Rock Properties Using NMR Data and + Generalized Interpolation-Based Techniques. Kwak, Hursan, Shao, Chen, Balliet, Eid, Guergueb + (2016). Petrophysics Vol. 57, No. 4 (August 2016), pp. 351-368. DOI: none assigned (this issue + predates SPWLA DOI assignment). +src2016_12/article6 -- Article 6 (Technical Note): Normalizing Gamma-Ray Logs Acquired from a + Mixture of Vertical and Horizontal Wells in the Haynesville Shale. Xu, Bayer, Wunderle, Bansal + (2016). Petrophysics Vol. 57, No. 6 (December 2016), pp. 638-643. DOI: none assigned (this issue + predates SPWLA DOI assignment). +src2017_08/article4 -- Article 4: The Impact of Depth and Pressure Measurement Errors on the + Estimation of Pressure Gradients. Bowers, Schnacke, Hermance (2017). Petrophysics Vol. 58, No. 4 + (August 2017), pp. 376-396. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2018_10/article11 -- Article 11: A New Hierarchical Method for Rock Classification Using Well- + Log-Based Rock Fabric Quantification. Purba, Garcia, Heidari (2018). DOI: + 10.30632/PJV59N5-2018a10. Petrophysics Vol. 59 No. 5 (Oct 2018) - "Best of 2018 SPWLA Symposium" + issue. +src2018_10/article5 -- Article 5: An Unsupervised Learning Algorithm to Compute Fluid Volumes From + NMR T1-T2 Logs in Unconventional Reservoirs. Venkataramanan, Evirgen, Allen, Mutina, Cai, + Johnson, Green, Jiang (2018). DOI: 10.30632/PJV59N5-2018a4. Petrophysics Vol. 59 No. 5 (Oct 2018) + - "Best of 2018 SPWLA Symposium" issue. +src2018_12 -- Petrophysics Vol. 59 No. 6 (Dec 2018) — Special Issue: Data-Driven Analytics in + Logging and Petrophysics (issue-level reference). +src2018_12/article11 -- Article 11: Data Preconditioning for Predictive and Interpretive + Algorithms: Importance in Data-Driven Analytics and Methods for Application. Frost, Quinn (2018). + DOI: 10.30632/PJV59N6Y2018a10. Petrophysics Vol. 59 No. 6 (Dec 2018) — Special Issue: Data-Driven + Analytics in Logging and Petrophysics. +src2018_12/article4 -- Article 4: Borehole Resistivity Measurement Modeling Using Machine-Learning + Techniques. Xu, Sun, Xie, Zhong, Mirto, Feng, Hong (2018). DOI: 10.30632/PJV59N6Y2018a3. + Petrophysics Vol. 59 No. 6 (Dec 2018) — Special Issue: Data-Driven Analytics in Logging and + Petrophysics. +src2019_08/article2 -- Article 2: Total Organic Carbon Characterization Using Neural-Network + Analysis of XRF Data. Lawal, Mahmoud, Alade, Abdulraheem (2019). DOI: 10.30632/PJV60N4-2019a2. + Petrophysics Vol. 60 No. 4 (Aug 2019). +src2019_10/article9 -- Article 9: Application of Artificial Neural Network to Predict Formation + Bulk Density While Drilling. Gowida, Elkatatny, Abdulraheem (2019). DOI: 10.30632/PJV60N5-2019a9. + Petrophysics Vol. 60 No. 5 (Oct 2019). +src2019_12/article7 -- Article 7: New Robust Model to Estimate Formation Tops in Real Time Using + Artificial Neural Networks (ANN). Elkatatny, Al-AbdulJabbar, Mahmoud (2019). DOI: + 10.30632/PJV60N6-2019a7. Petrophysics Vol. 60 No. 6 (Dec 2019). +src2019_12/article8 -- Article 8: A Comparative Study of Three Supervised Machine-Learning + Algorithms for Classifying Carbonate Vuggy Facies in the Kansas Arbuckle Formation. Deng, Xu, + Jobe, Xu (2019). DOI: 10.30632/PJV60N6-2019a8. Petrophysics Vol. 60 No. 6 (Dec 2019). +src2020_06/article5 -- Article 5: Estimation of Reservoir Porosity From Drilling Parameters Using + Artificial Neural Networks. Al-AbdulJabbar, Al-Azani, Elkatatny (2020). DOI: + 10.30632/PJV61N3-2020a5. Petrophysics Vol. 61 No. 3 (Jun 2020). +src2020_08/article4 -- Article 4: Detecting Specific Facies in Well-Log Data Sets Using Knowledge- + Driven Hierarchical Clustering. Emelyanova, Peyaud, Dance, Pervukhina (2020). DOI: + 10.30632/PJV61N4-2020a4. Petrophysics Vol. 61 No. 4 (Aug 2020). +src2020_10/article3 -- Article 3: Automatic Detection of Anomalous Density Measurements due to + Wellbore Cave-in. Sen, Ong, Kainkaryam, Sharma (2020). DOI: 10.30632/PJV61N5-2020a3. Petrophysics + Vol. 61 No. 5 (Oct 2020). +src2020_10/article7 -- Article 7: Integrated Multiphysics Workflow for Automatic Rock + Classification and Formation Evaluation Using Multiscale Image Analysis and Conventional Well + Logs. Gonzalez, Kanyan, Heidari, Lopez (2020). DOI: 10.30632/PJV61N5-2020a7. Petrophysics Vol. 61 + No. 5 (Oct 2020). +src2021_06 -- Petrophysics Vol. 62 No. 3 (Jun 2021) (issue-level reference). +src2021_06/article3 -- Article 3: Real-Time Prediction of Acoustic Velocities While Drilling + Vertical Complex Lithology Using AI Technique. Alsaihati, Elkatatny (2021). DOI: + 10.30632/PJV62N3-2021a2. Petrophysics Vol. 62 No. 3 (Jun 2021). +src2021_06/article3_ai_acoustic_velocity -- Article 3: Real-Time Prediction of Acoustic Velocities + While Drilling Vertical Complex Lithology Using AI Technique. Alsaihati, Elkatatny (2021). DOI: + 10.30632/PJV62N3-2021a2. Petrophysics Vol. 62 No. 3 (Jun 2021). +src2021_08 -- Petrophysics Vol. 62 No. 4 (Aug 2021) (issue-level reference). +src2021_08/article5 -- Article 5: Synthetic Sonic Log Generation With Machine Learning - A Contest + Summary From Five Methods. Yu, Xu, Misra, Li, Ashby, et al. (2021). DOI: 10.30632/PJV62N4-2021a4. + Petrophysics Vol. 62 No. 4 (Aug 2021). +src2021_12/article01 -- Article 1: Data Quality Considerations for Petrophysical Machine-Learning + Models. McDonald (2021). DOI: 10.30632/PJV62N6-2021a1. Petrophysics Vol. 62 No. 6 (Dec 2021). +src2021_12/article02 -- Article 2: Enhanced Mineral Quantification and Uncertainty Analysis From + Downhole Spectroscopy Logs Using Variational Autoencoders. Craddock, Srivastava, Datir, Rose, + Zhou, Mosse, Venkataramanan (2021). DOI: 10.30632/PJV62N6-2021a2. Petrophysics Vol. 62 No. 6 (Dec + 2021). +src2022_02/article4 -- Article 4: Ultrasonic Logging of Creeping Shale. Diez, Johansen, Larsen + (2022). DOI: 10.30632/PJV63N1-2022a4. Petrophysics Vol. 63 No. 1 (Feb 2022). +src2022_10 -- Petrophysics Vol. 63 No. 5 (Oct 2022) (issue-level reference). +src2022_10/article1 -- Article 1: A Guide to Nanoindentation. Sondergeld, Rai (2022). DOI: + 10.30632/PJV63N5-2022a1. Petrophysics Vol. 63 No. 5 (Oct 2022). +src2023_04/article02 -- Article 2: Data-Driven Algorithms for Image-Based Rock Classification and + Formation Evaluation in Formations With Rapid Spatial Variation in Rock Fabric. Gonzalez, + Heidari, and Lopez (2023). DOI: 10.30632/PJV64N2-2023a2. Petrophysics Vol. 64 No. 2 (Apr 2023) — + SPWLA AI/ML Special Issue. +src2024_10 -- Petrophysics Vol. 65 No. 5 (Oct 2024) (issue-level reference). +src2024_10/lithofacies_prediction -- High-Resolution Lithofacies Prediction Using Ensemble + Classifiers. Based on: Satti et al. (2024), "Enhancing Reservoir Characterization With High- + Resolution Lithofacies Prediction Using Advanced Feature Engineering and Ensemble Classifiers", + Petrophysics, Vol. 65, No. 5, pp. 813-834. """ from __future__ import annotations @@ -318,7 +430,10 @@ def ols(X: ArrayLike, y: ArrayLike, *, intercept: bool = True) -> tuple[_Float, def predict_linear(X: ArrayLike, coef: ArrayLike, intercept: float = 0.0) -> _Float: - """Evaluate the linear model from :func:`ols`.""" + """Evaluate the linear model from :func:`ols`. + + Sources: src2021_06/article3_ai_acoustic_velocity. + """ design = np.asarray(X, np.float64) if design.ndim == 1: design = design[:, None] diff --git a/petrolib/nmr.py b/petrolib/nmr.py index cc622ba..db566e7 100644 --- a/petrolib/nmr.py +++ b/petrolib/nmr.py @@ -28,6 +28,145 @@ um/s, S/V in 1/um, diffusivity D in um2/ms, gradient G in T/m, echo spacing TE in ms, permeability in mD, porosity a fraction. numpy-only at import; any fit/inversion routine imports scipy lazily. + +References +---------- +Complete citations for the source tags used in this module (SPWLA journal +*Petrophysics*): + +src2014_06/article3 -- Article 3: Magnetic Resonance Core-Plug Analysis with the Three-Magnet Array + Unilateral Magnet Juan C. Garcia-Naranjo, Pan Guo, Florin Marica, Guangzhi Liao, Bruce J. Balcom + (2014). Petrophysics Vol. 55, No. 3 (June 2014), pp. 229-239. DOI: none assigned (this issue + predates SPWLA DOI assignment). +src2014_06/article4 -- Article 4: Method for Predicting Permeability of Complex Carbonate + Reservoirs Using NMR Logging Measurements Willian Trevizan, Paulo Neto, Bernardo Coutinho, + Vinicius F. Machado, Edmilson H. Rios, Songhua Chen, Wei Shao, Pedro Romero (2014). Petrophysics + Vol. 55, No. 3 (June 2014), pp. 240-252. DOI: none assigned (this issue predates SPWLA DOI + assignment). +src2014_12/article3 -- Article 3: Experimental Study of the Effects of Wettability and Fluid + Saturation on NMR and Dielectric Measurements in Limestone Lalitha Venkataramanan, Martin D. + Hurlimann, Jeffrey A. Tarvin, Kamilla Fellah, Diana Acero-Allard, Nikita V. Seleznev (2014). + Petrophysics Vol. 55, No. 6 (December 2014), pp. 572-586. DOI: none assigned (this issue predates + SPWLA DOI assignment). +src2015_02/article3 -- Article 3: Coupling Multiphase Hydrodynamic and NMR Pore-Scale Modeling for + Advanced Characterization of Saturated Rocks. Evseev, Dinariev, Hurlimann, Safonov (2015). + Petrophysics Vol. 56, No. 1 (February 2015), pp. 32-44. DOI: none assigned (this issue predates + SPWLA DOI assignment). +src2015_04/article5 -- Article 5: New Method to Estimate Porosity More Accurately from NMR Data + with Short Relaxation Times. Venkataramanan, Gruber, LaVigne, Habashy, Iglesias, Cohorn, Anand, + Rampurawala, Jain, Heaton, Akkurt, Rylander, Lewis (2015). Petrophysics Vol. 56, No. 2 (April + 2015), pp. 147-157. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2015_08/article1 -- Article 1: Subsurface Fluid Characterization Using Downhole and Core NMR + T1-T2 Maps Combined with Pore-Scale Imaging Techniques. Lessenger, Merkel, Medina, Ramakrishna, + Chen, Balliet, Xie, Bhattad, Carnerup, Knackstedt (2015). Petrophysics Vol. 56, No. 4 (August + 2015), pp. 313-333. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2015_10/article3 -- Article 3: Using Advanced Logging Measurements to Develop a Robust + Petrophysical Model for the Bakken Petroleum System. Simpson, Hohman, Pirie, Horkowitz (2015). + Petrophysics Vol. 56, No. 5 (October 2015), pp. 457-478. DOI: none assigned (this issue predates + SPWLA DOI assignment). +src2015_12/article1 -- Article 1: Reservoir Characterization Challenges Due to the Multiscale + Spatial Heterogeneity in the Presalt Carbonate Sag Formation, North Campos Basin, Brazil. + Chitale, Alabi, Gramin, Lepley, Piccoli (2015). Petrophysics Vol. 56, No. 6 (December 2015), pp. + 552-576. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2016_02/article2 -- Article 2: Estimating Saturations in Organic Shales Using 2D NMR. Nicot, + Vorapalawut, Rousseau, Madariaga, Hamon, Korb (2016). Petrophysics Vol. 57, No. 1 (February + 2016), pp. 19-29. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2016_08/article1 -- Article 1: NMR Relaxometry in Shale and Implications for Logging. Kausik, + Fellah, Rylander, Singer, Lewis, Sinclair (2016). Petrophysics Vol. 57, No. 4 (August 2016), pp. + 339-350. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2016_08/article2 -- Article 2: Predicting Carbonate Rock Properties Using NMR Data and + Generalized Interpolation-Based Techniques. Kwak, Hursan, Shao, Chen, Balliet, Eid, Guergueb + (2016). Petrophysics Vol. 57, No. 4 (August 2016), pp. 351-368. DOI: none assigned (this issue + predates SPWLA DOI assignment). +src2016_12/article4 -- Article 4: Fluid Typing and Pore Size in Organic Shale Using 2D NMR in + Saturated Kerogen Isolates. Singer, Chen, Hirasaki (2016). Petrophysics Vol. 57, No. 6 (December + 2016), pp. 604-619. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2017_04/article3 -- Article 3: A Laboratory Study of the Link Between NMR Relaxation Data and + Pore Size In Carbonate Skeletal Grains and Micrite. El-Husseiny, Knight (2017). Petrophysics Vol. + 58, No. 2 (April 2017), pp. 116-125. DOI: none assigned (this issue predates SPWLA DOI + assignment). +src2017_04/article4 -- Article 4: Low-Field NMR Spectrometry of Chalk and Argillaceous Sandstones: + Rock-Fluid Affinity Assessed from T1/T2 Ratio. Katika, Saidian, Prasad, Fabricius (2017). + Petrophysics Vol. 58, No. 2 (April 2017), pp. 126-140. DOI: none assigned (this issue predates + SPWLA DOI assignment). +src2017_06/article2 -- Article 2: A Novel Determination of Total Gas-In-Place (TGIP) for Gas Shale + From Magnetic Resonance Logs. Kausik, Kleinberg, Rylander, Lewis, Sibbit, Westacott (2017). + Petrophysics Vol. 58, No. 3 (June 2017), pp. 232-241. DOI: none assigned (this issue predates + SPWLA DOI assignment). +src2017_08/article1 -- Article 1: High- and Low-Field NMR Relaxometry and Diffusometry of the + Bakken Petroleum System. Kausik, Fellah, Feng, Simpson (2017). Petrophysics Vol. 58, No. 4 + (August 2017), pp. 341-351. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2017_10/article2 -- Article 2: Effects of Bitumen Extraction on the 2D NMR Response of Saturated + Kerogen Isolates. Chen, Singer, Kuang, Vargas, Hirasaki (2017). Petrophysics Vol. 58, No. 5 + (October 2017), pp. 470-484. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2018_04/article3 -- Article 3: Nuclear Magnetic Resonance and Pore Coupling in Clay-Coated + Sandstones With Anomalous Porosity Preservation, Agua Grande Formation, Reconcavo Basin, Brazil. + Jacomo, Trindade, de Oliveira, Leite, Montrazi, Andreeta, Bonagamba (2018). DOI: + 10.30632/PJV59N2-2018a2. Petrophysics Vol. 59 No. 2 (Apr 2018). +src2019_02/article3 -- Article 3: Frequency and Temperature Dependence of 2D NMR T1-T2 Maps of + Shale. Kausik, Freed, Fellah, Feng, Ling, Simpson (2019). DOI: 10.30632/PJV60N1Y2019a2. + Petrophysics Vol. 60 No. 1 (Feb 2019). +src2019_06/article5 -- Article 5: Application of a Fast NMR T1 Relaxation Time Measurement to + Sedimentary Rock Cores. Mitchell, Valori (2019). DOI: 10.30632/PJV60N3-2019a4. Petrophysics Vol. + 60 No. 3 (Jun 2019). +src2019_12/article5 -- Article 5: NMR Evaluation of Light-Hydrocarbon Composition, Pore Size, and + Tortuosity in Organic-Rich Chalks. Chen, Singer, Wang, Vinegar, Nguyen, Hirasaki (2019). DOI: + 10.30632/PJV60N6-2019a5. Petrophysics Vol. 60 No. 6 (Dec 2019). +src2019_12/article6 -- Article 6: Influence of Magnetic Susceptibility Contrast on NMR Studies - + Experimental Analysis From Siliciclastic Reservoirs. Sarkar, Chatterjee, Lal, Kumar, Deo (2019). + DOI: 10.30632/PJV60N6-2019a6. Petrophysics Vol. 60 No. 6 (Dec 2019). +src2020_04/article2 -- Article 2: A New Apparatus for Coupled Low-Field NMR and Ultrasonic + Measurements in Rocks at Reservoir Conditions. Connolly, Sarout, Dautriat, May, Johns (2020). + DOI: 10.30632/PJV61N2-2020a2. Petrophysics Vol. 61 No. 2 (Apr 2020). +src2021_04/article1 -- Article 1: Pore-Structure Characterization of a Complex Carbonate Reservoir + in South Iraq Using Advanced Interpretation of NMR Logs. Saidian, Jain, Milad (2021). DOI: + 10.30632/PJV62N2-2021a1. Petrophysics Vol. 62 No. 2 (Apr 2021). +src2021_04/article5 -- Article 5: An Integrated Petrophysical Workflow for Fluid Characterization + and Contacts Identification Using NMR Continuous and Stationary Measurements in a High-Porosity + Sandstone Formation, Offshore Norway. Kozlowski, Chakraborty, Jambunathan, Lowrey, Balliet, + Engelman, Anensen, Kotwicki, Johansen (2021). DOI: 10.30632/PJV62N2-2021a5. Petrophysics Vol. 62 + No. 2 (Apr 2021). +src2021_06/article2 -- Article 2: Pore Size, Tortuosity, and Permeability From NMR Restricted + Diffusion in Organic-Rich Chalks. Wang, Singer, Liu, Chen, Hirasaki, Vinegar (2021). DOI: + 10.30632/PJV62N3-2021a1. Petrophysics Vol. 62 No. 3 (Jun 2021). +src2021_08/article3 -- Article 3: NMR Fluid Substitution - A New Method of Reconstructing T2 + Distributions Under Primary Drainage and Imbibition Conditions. Li, Kesserwan, Jin, Ma (2021). + DOI: 10.30632/PJV62N4-2021a2. Petrophysics Vol. 62 No. 4 (Aug 2021). +src2022_06/article1 -- Article 1: Integrated Reservoir Characterization Using Unsupervised Learning + on Nuclear Magnetic Resonance (NMR) T1-T2 Logs. Jiang, Bonnie, Correa, Krueger, Kelly, Wasson + (2022). DOI: 10.30632/PJV63N3-2022a1. Petrophysics Vol. 63 No. 3 (Jun 2022) — NMR SIG Special + Issue. +src2022_06/article3 -- Article 3: NMR Logging Data Processing. Shao, Balliet (2022). DOI: + 10.30632/PJV63N3-2022a3. Petrophysics Vol. 63 No. 3 (Jun 2022) — NMR SIG Special Issue. +src2022_06/article5 -- Article 5: NMR T1-T2 Logging in Unconventional Reservoirs: Pore-Size. + Distribution, Permeability, and Reservoir Quality. Ijasan, Macquaker, Luycx, Alzobaidi, Oyewole, + Rudnicki (2022). DOI: 10.30632/PJV63N3-2022a5. Petrophysics Vol. 63 No. 3 (Jun 2022) — NMR SIG + Special Issue. +src2024_06/article6 -- Althaus, S., Chen, J., Sun, Q., and Broyles, J. D. (2024). "Determine Oil + and Water Saturations in Preserved Source Rocks From 2D T1-T2 NMR." Petrophysics 65(3), 388-396. + DOI: 10.30632/PJV65N3-2024a6. +src2025_02/mr_bulk_saturation -- Bulk Saturation Measurement Using 13C and 1H Magnetic Resonance. + Ansaribaranghar et al., 2025, Petrophysics 66(1), 155-168. DOI:10.30632/PJV66N1-2025a11. +src2025_04/unconventional_porosity -- Laboratory Measurement of Total Porosity and Fluid + Saturations for Unconventional Tight Rocks. Based on: Cheng et al., "Laboratory Measurement of + Total Porosity and Fluid Saturations for Unconventional Tight Rocks: Methodologies, Challenges, + and Comparison", Petrophysics, Vol. 66, No. 2, April 2025, pp. 250–266. +src2025_06/cross_calibrated_permeability -- Cross-Calibrated Permeabilities: A Reliable and + Physically Coherent Methodology Implements the methodology from: Sifontes, V., Leal, L.A., + Farfan, M., and Mussio Arias, A., 2025, "Cross-Calibrated Permeabilities: A Reliable and + Physically Coherent Methodology," Petrophysics, Vol. 66, No. 3, pp. 449–466. +src2025_10/a6 -- Article 6: Enhanced Learning Experience for New Petrophysicists Using Open-Source + Carbonate Data and Python Programming Author: Imran M. Fadhil Ref: Petrophysics, Vol. 66, No. 5 + (October 2025), pp. 807-838. DOI: 10.30632/PJV66N5-2025a6. +src2026_02/nmr_discrete_inversion -- Article 3: Discrete Inversion Method for Nuclear Magnetic + Resonance Data Processing and Its Applications to Fluid Typing and Quantification. Gao et al. + (2026), Petrophysics, 67(1), 38-53. DOI: 10.30632/PJV67N1-2026a3. +src2026_04/a07 -- Yu, H., Pan, B., Guo, Y., Wang, Y., Zhou, Y., and Li, Y. (2026). A Knowledge- + Guided Data-Driven Method for Predicting Reservoir Parameters. Petrophysics, 67(2), 351–373. DOI: + 10.30632/PJV67N2-2026a7. +src2026_06/a03 -- Manuaba, I. B. G. H., Najrani, H., Cavalleri, C., Moge, A., and Chapura, M. + (2026). Effect of Pore-Size Distribution on Fluid Movement in Complex Reservoirs. Petrophysics, + 67(3), 509-524. DOI: 10.30632/PJV67N3-2026a3 (orig. SPE-227259-MS). """ from __future__ import annotations diff --git a/petrolib/nuclear.py b/petrolib/nuclear.py index 7a38937..09d4e1e 100644 --- a/petrolib/nuclear.py +++ b/petrolib/nuclear.py @@ -16,6 +16,103 @@ endpoint interpolation in several term orders and coefficient conventions; the canonical forms here take the recurring defaults, and the article facades map their own constants onto the keyword parameters. + +References +---------- +Complete citations for the source tags used in this module (SPWLA journal +*Petrophysics*): + +src2014_06/article2_borehole_carbon_toc -- Article 2: Borehole Carbon Corrections Enable Accurate + TOC Determination from Nuclear Spectroscopy. Jeffrey Miles and Rob Badry (2014). Petrophysics + Vol. 55, No. 3 (June 2014), pp. 219-228. DOI: none assigned (this issue predates SPWLA DOI + assignment). +src2014_08/article6_siliceous_ooze_petrophysics -- Article 6: Petrophysical Analysis of Siliceous- + Ooze Sediments, More Basin, Norwegian Sea. Ahmed Awadalkarim, Morten Kanne Sorensen, Ida Lykke + Fabricius (2014). Petrophysics Vol. 55, No. 4 (August 2014), pp. 333-348. DOI: none assigned + (this issue predates SPWLA DOI assignment). +src2014_10/article3_nuclear_density_alternatives -- Article 3: An Assessment of Fundamentals of + Nuclear-Based Alternatives to Conventional Chemical-Source Bulk-Density Measurement. Ahmed + Badruzzaman (2014). Petrophysics Vol. 55, No. 5 (October 2014), pp. 415-434. DOI: none assigned + (this issue predates SPWLA DOI assignment). +src2014_12/article5_cased_well_gas_saturation -- Article 5: Physical Basis for a Cased-Well + Quantitative Gas-Saturation Analysis Method. F. Inanc, W.A. Gilchrist, R. Ansari, D. Chace + (2014). Petrophysics Vol. 55, No. 6 (December 2014), pp. 598-617. DOI: none assigned (this issue + predates SPWLA DOI assignment). +src2015_02/article5_through_the_bit_logging -- Article 5: Recharacterization and Validation of + Through-the-Bit-Logging Tool Measurements. Slocombe, Bammi, Hunka, Reischman, Schmid (2015). + Petrophysics Vol. 56, No. 1 (February 2015), pp. 58-71. DOI: none assigned (this issue predates + SPWLA DOI assignment). +src2015_08/article2_condensed_vapor_gamma -- Article 2: In-Situ Evaluation of Vapor Properties + Using Condensed Vapor Gamma. O'Sullivan (2015). Petrophysics Vol. 56, No. 4 (August 2015), pp. + 334-345. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2016_08/article4_spectral_gr_mwd -- Article 4: Spectral Gamma-Ray Measurement While Drilling. + Xu, Huiszoon, Wang, Adolph, Yi, Cavin, Laughlin, Tollefsen, Jacobsen, Boyce (2016). Petrophysics + Vol. 57, No. 4 (August 2016), pp. 377-389. DOI: none assigned (this issue predates SPWLA DOI + assignment). +src2017_08/article1_bakken_nmr_relaxometry -- Article 1: High- and Low-Field NMR Relaxometry and + Diffusometry of the Bakken Petroleum System. Kausik, Fellah, Feng, Simpson (2017). Petrophysics + Vol. 58, No. 4 (August 2017), pp. 341-351. DOI: none assigned (this issue predates SPWLA DOI + assignment). +src2017_08/article6_fast_neutron_gamma_density -- Article 6: A Method of Determining Formation + Density Based on Fast-Neutron Gamma Coupled Field Theory. Zhang, Zhang, Liu, Wu, Wu, Jia, Ti, Li + (2017). Petrophysics Vol. 58, No. 4 (August 2017), pp. 411-425. DOI: none assigned (this issue + predates SPWLA DOI assignment). +src2018_04/article1_shaly_sand_tutorial_part2 -- Article 1 (Tutorial): What is it about Shaly + Sands? Shaly Sand Tutorial No. 2 of 3. Thomas (2018). DOI: 10.30632/PJV59N2-2018t1. Petrophysics + Vol. 59 No. 2 (Apr 2018). +src2018_04/article4_neutron_xray_imaging -- Article 4: Simultaneous Neutron and X-Ray Imaging of 3D + Structure of Organic Matter and Fracture in Shales. Chiang, LaManna, Hussey, Jacobson, Liu, + Zhang, Georgi, Kone, Chen (2018). DOI: 10.30632/PJV59N2-2018a3. Petrophysics Vol. 59 No. 2 (Apr + 2018). +src2018_10/article2_xray_sourceless_density -- Article 2: A Novel X-Ray Tool for True Sourceless + Density Logging. Simon, Tkabladze, Beekman, Atobatele, De Looz, Grover, Hamichi, Jundt, + McFarland, Mlcak, Reijonen, Revol, Stewart, Yeboah, Zhang (2018). DOI: 10.30632/PJV59N5-2018a1. + Petrophysics Vol. 59 No. 5 (Oct 2018) - "Best of 2018 SPWLA Symposium" issue. +src2019_04/article7_issm_saturation_monitoring -- Article 7: In-Situ Saturation Monitoring (ISSM) - + Recommendations for Improved Processing. Reed, Cense (2019). DOI: 10.30632/PJV60N2-2019a5. + Petrophysics Vol. 60 No. 2 (Apr 2019). +src2019_10/article1_tmali_organic_shales -- Article 1: Thermal Maturity-Adjusted Log Interpretation + (TMALI) in Organic Shales. Craddock, Miles, Lewis, Pomerantz (2019). DOI: + 10.30632/PJV60N5-2019a1. Petrophysics Vol. 60 No. 5 (Oct 2019). +src2019_10/article5_log_soak_log_imbibition -- Article 5: 'Log-Soak-Log' Experiment in Tengiz + Field: Novel Technology for In-Situ Imbibition Measurements to Support an Improved Oil Recovery + Project. Seth, Villegas, Iskakov, Playton, Lindsell, Cordova, Turmanbekova, Wang (2019). DOI: + 10.30632/PJV60N5-2019a5. Petrophysics Vol. 60 No. 5 (Oct 2019). +src2020_06/article1_casedhole_horizontal_fe -- Article 1: Lessons Learned From Casedhole Formation + Evaluation Along Unconventional Horizontal Wells. Sullivan, Wang, Bolshakov, Song, Lazorek, + Tohidi, Seth (2020). DOI: 10.30632/PJV61N3-2020a1. Petrophysics Vol. 61 No. 3 (Jun 2020). +src2020_06/article2_cement_quality_co_pulsed_neutron -- Article 2: Case Studies Demonstrating the + Impact of Cement Quality on Carbon/Oxygen and Elemental Analysis From Casedhole Pulsed-Neutron + Logging. Wang, Sullivan, Seth, Barnes, Wilson, Lazorek (2020). DOI: 10.30632/PJV61N3-2020a2. + Petrophysics Vol. 61 No. 3 (Jun 2020). +src2020_12/article1_nuclear_spectroscopy_history -- Article 1: A History of Nuclear Spectroscopy in + Well Logging. Pemper (2020). DOI: 10.30632/PJV61N6-2020a1. Petrophysics Vol. 61 No. 6 (Dec 2020). +src2020_12/article2_formation_chlorine_salinity -- Article 2: Formation Chlorine Measurement From + Spectroscopy Enables Water Salinity Interpretation: Theory, Modeling, and Applications. Miles, + Mosse, Grau (2020). DOI: 10.30632/PJV61N6-2020a2. Petrophysics Vol. 61 No. 6 (Dec 2020). +src2020_12/article3_self_compensated_spectroscopy -- Article 3: Self-Compensated Pulsed-Neutron + Spectroscopy Measurements. Zhou, Rose, Miles, Gendur, Wang, Sullivan (2020). DOI: + 10.30632/PJV61N6-2020a3. Petrophysics Vol. 61 No. 6 (Dec 2020). +src2020_12/article4_co_sigma_saturation_casestudy -- Article 4: New Generation of Pulsed-Neutron + Multidetector Comparison in a Challenging Multistack Clastic Reservoir - A Case Study in a Brown + Field, Malaysia. Johare, Mohd Amin, Prasodjo, Afandi, Din (2020). DOI: 10.30632/PJV61N6-2020a4. + Petrophysics Vol. 61 No. 6 (Dec 2020). +src2020_12/article7_sigma_gas_saturation_lowporosity -- Article 7: Multidetector Pulsed-Neutron + Tool Application in a Low-Porosity Reservoir - A Case Study in Mutiara Field, Indonesia. Wijaya, + Aulianagara, Guo, Naibaho, Asriwan, Amirudin (2020). DOI: 10.30632/PJV61N6-2020a7. Petrophysics + Vol. 61 No. 6 (Dec 2020). +src2023_08/article1_nuclear_logging -- Fitz, D.E. (2023). "Evolution of Casedhole Nuclear + Surveillance Logging Through Time", Petrophysics, Vol. 64, No. 4 (August 2023), pp. 473-501. DOI: + 10.30632/PJV64N4-2023a1. +src2023_10/article_05_laronga_pulsed_neutron_ccs -- Laronga, R., Swager, L., and Bustos, U. (2023). + "Time-Lapse Pulsed- Neutron Logs for Carbon Capture and Sequestration: Practical Learnings and + Key Insights." Petrophysics, 64(5), 680-699. DOI: 10.30632/PJV64N5-2023a5. +src2023_12/mcglynn_pulsed_neutron -- McGlynn et al. (2023), Petrophysics 64(6): 900-918. New + pulsed-neutron spectroscopy instrument with LaBr3 detectors providing simultaneous C/O ratio, + capture sigma, and ratio-based gas measurements for two- and three-phase saturation analysis. +src2024_06/article1_nuclear_logging_ccs -- Badruzzaman, A. (2024). "Nuclear Logging in Geological + Probing for a Low-Carbon Energy Future - A New Frontier?" Petrophysics 65(3), 274-301. DOI: + 10.30632/PJV65N3-2024a1. """ from __future__ import annotations @@ -59,6 +156,9 @@ def sigma_forward( ``Sigma = (1-phi-Vsh)*Sigma_ma + Vsh*Sigma_sh + phi*(Sw*Sigma_w + (1-Sw)*Sigma_hc)``. With ``vsh=0`` this is the clean two-phase form. + + Sources: src2020_12/article7_sigma_gas_saturation_lowporosity, + src2023_08/article1_nuclear_logging, src2023_10/article_05_laronga_pulsed_neutron_ccs. """ phi_a = _arr(phi) sw_a = _arr(sw) @@ -82,6 +182,8 @@ def sigma_forward_3phase( """Three-phase (oil/gas/water) capture cross-section ``Sigma`` (c.u.). ``Sigma = (1-phi)*Sigma_ma + phi*(So*Sigma_oil + Sg*Sigma_gas + Sw*Sigma_w)``. + + Sources: src2023_12/mcglynn_pulsed_neutron. """ phi_a = _arr(phi) fluid = _arr(so) * sigma_oil + _arr(sg) * sigma_gas + _arr(sw) * sigma_w @@ -103,6 +205,12 @@ def sw_from_sigma( ``Sw = (Sigma_t - (1-phi-Vsh)*Sigma_ma - Vsh*Sigma_sh - phi*Sigma_hc) / (phi*(Sigma_w - Sigma_hc))``. ``clip`` bounds the result (``None`` to skip). + + Sources: src2019_10/article1_tmali_organic_shales, + src2019_10/article5_log_soak_log_imbibition, src2020_06/article1_casedhole_horizontal_fe, + src2020_06/article2_cement_quality_co_pulsed_neutron, + src2020_12/article4_co_sigma_saturation_casestudy, + src2020_12/article7_sigma_gas_saturation_lowporosity. """ sigma_ta = _arr(sigma_t) phi_a = _arr(phi) @@ -136,7 +244,11 @@ def delta_sw_timelapse( def sigma_sensitivity(phi: ArrayLike, sigma_w: float, sigma_hc: float) -> _Float: - """Saturation sensitivity ``dSigma/dSw = phi*(Sigma_w - Sigma_hc)`` (c.u.).""" + """Saturation sensitivity ``dSigma/dSw = phi*(Sigma_w - Sigma_hc)`` (c.u.). + + Sources: src2019_10/article5_log_soak_log_imbibition, + src2020_12/article7_sigma_gas_saturation_lowporosity. + """ return np.asarray(_arr(phi) * (sigma_w - sigma_hc)) @@ -147,6 +259,8 @@ def sigma_w_from_salinity( ``model='fitz2023'``: ``(22 + 750*s)*(1 - 8e-4*(T-75))`` with ``s=ppm/1e6``. ``model='linear450k'``: ``22 + (220-22)*ppm/450000``. + + Sources: src2019_10/article5_log_soak_log_imbibition, src2023_08/article1_nuclear_logging. """ ppm = _arr(ppm_nacl) if model == "fitz2023": @@ -158,7 +272,10 @@ def sigma_w_from_salinity( def number_density(rho_g_cc: ArrayLike, wfrac: ArrayLike, atomic_mass: ArrayLike) -> _Float: - """Atomic number density ``N = rho*NA*w/A`` (1/cm3) for a mass fraction ``w``.""" + """Atomic number density ``N = rho*NA*w/A`` (1/cm3) for a mass fraction ``w``. + + Sources: src2020_12/article1_nuclear_spectroscopy_history. + """ return np.asarray(_arr(rho_g_cc) * NA * _arr(wfrac) / _arr(atomic_mass)) @@ -169,6 +286,8 @@ def macroscopic_sigma( ``Sigma = sum_i N_i * sigma_i`` with ``sigma`` in barns (1 barn = 1e-24 cm2); ``units='cu'`` returns c.u. (cm^-1 * 1e3), ``units='cm'`` returns cm^-1. + + Sources: src2020_12/article1_nuclear_spectroscopy_history. """ sigma_cm = np.sum(_arr(number_densities) * _arr(micro_barns) * 1e-24) if units == "cu": @@ -179,12 +298,18 @@ def macroscopic_sigma( def sigma_from_tau(tau_us: ArrayLike) -> _Float: - """Capture cross-section from thermal decay time ``Sigma = 4550/tau`` (c.u.).""" + """Capture cross-section from thermal decay time ``Sigma = 4550/tau`` (c.u.). + + Sources: src2020_12/article1_nuclear_spectroscopy_history. + """ return np.asarray(SIGMA_TAU_CONST / _arr(tau_us)) def tau_from_sigma(sigma_cu: ArrayLike) -> _Float: - """Thermal decay time from capture cross-section ``tau = 4550/Sigma`` (us).""" + """Thermal decay time from capture cross-section ``tau = 4550/Sigma`` (us). + + Sources: src2020_12/article1_nuclear_spectroscopy_history. + """ return np.asarray(SIGMA_TAU_CONST / _arr(sigma_cu)) @@ -193,6 +318,8 @@ def pnc_decay(t_us: ArrayLike, n0: float, sigma_cu: float, *, background: float ``Sigma`` (c.u.) is converted to cm^-1 (``*1e-3``), ``v`` is the thermal-neutron velocity, and ``t`` (us) to seconds (``*1e-6``). + + Sources: src2024_06/article1_nuclear_logging_ccs. """ sigma_cm = sigma_cu * 1e-3 decay_rate = sigma_cm * THERMAL_NEUTRON_VELOCITY_CM_S @@ -222,17 +349,27 @@ def sigma_from_decay_fit( def beer_lambert(i0: ArrayLike, mu: ArrayLike, x: ArrayLike) -> _Float: - """Beer-Lambert transmitted intensity ``I = I0*exp(-mu*x)``.""" + """Beer-Lambert transmitted intensity ``I = I0*exp(-mu*x)``. + + Sources: src2014_10/article3_nuclear_density_alternatives, + src2018_04/article4_neutron_xray_imaging, src2019_04/article7_issm_saturation_monitoring. + """ return np.asarray(_arr(i0) * np.exp(-_arr(mu) * _arr(x))) def mu_from_intensity(i0: ArrayLike, i: ArrayLike, x: ArrayLike) -> _Float: - """Linear attenuation coefficient ``mu = ln(I0/I)/x`` from an intensity pair.""" + """Linear attenuation coefficient ``mu = ln(I0/I)/x`` from an intensity pair. + + Sources: src2019_04/article7_issm_saturation_monitoring. + """ return np.asarray(np.log(_arr(i0) / _arr(i)) / _arr(x)) def attenuation_map(i: ArrayLike, i_ref: ArrayLike) -> _Float: - """Optical-density attenuation ``-ln(I/I_ref)`` (zero-guarded ratio).""" + """Optical-density attenuation ``-ln(I/I_ref)`` (zero-guarded ratio). + + Sources: src2018_04/article4_neutron_xray_imaging. + """ ratio = np.divide(_arr(i), _arr(i_ref)) return np.asarray(-np.log(np.clip(ratio, 1e-30, None))) @@ -240,14 +377,22 @@ def attenuation_map(i: ArrayLike, i_ref: ArrayLike) -> _Float: def gamma_count( rho: ArrayLike, *, n0: float = 1e6, mu_mass: float = 0.06, spacing_cm: float = 30.0 ) -> _Float: - """Gamma count rate vs density ``N = N0*exp(-mu_mass*rho*spacing)``.""" + """Gamma count rate vs density ``N = N0*exp(-mu_mass*rho*spacing)``. + + Sources: src2017_08/article6_fast_neutron_gamma_density, + src2018_10/article2_xray_sourceless_density. + """ return np.asarray(n0 * np.exp(-mu_mass * _arr(rho) * spacing_cm)) def density_from_count( count: ArrayLike, *, n0: float = 1e6, mu_mass: float = 0.06, spacing_cm: float = 30.0 ) -> _Float: - """Density from a gamma count ``rho = ln(N0/N)/(mu_mass*spacing)`` (inverse).""" + """Density from a gamma count ``rho = ln(N0/N)/(mu_mass*spacing)`` (inverse). + + Sources: src2017_08/article6_fast_neutron_gamma_density, + src2018_10/article2_xray_sourceless_density. + """ return np.asarray(np.log(n0 / _arr(count)) / (mu_mass * spacing_cm)) @@ -257,7 +402,11 @@ def density_from_count( def dual_detector_density(near: ArrayLike, far: ArrayLike, *, a: float, b: float) -> _Float: - """Dual-detector density ``rho = a + b*ln(near/far)`` (count-ratio calibration).""" + """Dual-detector density ``rho = a + b*ln(near/far)`` (count-ratio calibration). + + Sources: src2014_10/article3_nuclear_density_alternatives, + src2017_08/article6_fast_neutron_gamma_density. + """ return np.asarray(a + b * np.log(_arr(near) / _arr(far))) @@ -271,6 +420,8 @@ def spine_ribs( ``drho = c0 + c1*d + c2*d**2`` with ``d = rho_ls - rho_ss`` (long-short spacing); ``rho_b = rho_ls + drho``. + + Sources: src2018_10/article2_xray_sourceless_density. """ d = _arr(rho_ls) - _arr(rho_ss) c0, c1, c2 = rib_coeffs @@ -279,20 +430,30 @@ def spine_ribs( def electron_density_index(z: ArrayLike, a: ArrayLike, rho_m: ArrayLike) -> _Float: - """Electron density ``rho_e = (2*Z/A)*rho_m`` of a single element/compound.""" + """Electron density ``rho_e = (2*Z/A)*rho_m`` of a single element/compound. + + Sources: src2015_02/article5_through_the_bit_logging, + src2019_10/article1_tmali_organic_shales. + """ return np.asarray((2.0 * _arr(z) / _arr(a)) * _arr(rho_m)) def electron_density_mixture( z: ArrayLike, a: ArrayLike, mass_frac: ArrayLike, rho_m: ArrayLike ) -> _Float: - """Mixture electron density ``rho_e = 2*sum(w_i*Z_i/A_i)*rho_m``.""" + """Mixture electron density ``rho_e = 2*sum(w_i*Z_i/A_i)*rho_m``. + + Sources: src2015_02/article5_through_the_bit_logging. + """ zam = np.sum(_arr(mass_frac) * _arr(z) / _arr(a)) return np.asarray(2.0 * zam * _arr(rho_m)) def rhob_from_rhoe(rho_e: ArrayLike) -> _Float: - """Bulk density from electron density ``rho_b = 1.0704*rho_e - 0.1883``.""" + """Bulk density from electron density ``rho_b = 1.0704*rho_e - 0.1883``. + + Sources: src2019_10/article1_tmali_organic_shales. + """ return np.asarray(RHOE_TO_RHOB_SLOPE * _arr(rho_e) - RHOE_TO_RHOB_OFFSET) @@ -317,6 +478,10 @@ def gr_api( Default ``coeff=(16, 8, 4)`` (K wt%, U ppm, Th ppm); pass e.g. ``(16.32, 8.09, 3.93)`` for the alternative calibration. + + Sources: src2016_08/article4_spectral_gr_mwd, + src2018_04/article1_shaly_sand_tutorial_part2, src2020_06/article1_casedhole_horizontal_fe, + src2020_12/article1_nuclear_spectroscopy_history. """ ck, cu, cth = coeff return np.asarray(ck * _arr(k_pct) + cu * _arr(u_ppm) + cth * _arr(th_ppm)) @@ -325,7 +490,10 @@ def gr_api( def cgr_api( k_pct: ArrayLike, th_ppm: ArrayLike, *, coeff: tuple[float, float] = (16.0, 4.0) ) -> _Float: - """Computed (uranium-free) gamma ray API ``CGR = ck*K + cth*Th``.""" + """Computed (uranium-free) gamma ray API ``CGR = ck*K + cth*Th``. + + Sources: src2016_08/article4_spectral_gr_mwd. + """ ck, cth = coeff return np.asarray(ck * _arr(k_pct) + cth * _arr(th_ppm)) @@ -366,23 +534,35 @@ def hydrogen_index_chemical( def hi_mix(phi: ArrayLike, *, hi_fluid: float = 1.0, hi_matrix: float = 0.0) -> _Float: - """Volumetric hydrogen-index log ``HI = phi*HI_fluid + (1-phi)*HI_matrix``.""" + """Volumetric hydrogen-index log ``HI = phi*HI_fluid + (1-phi)*HI_matrix``. + + Sources: src2014_08/article6_siliceous_ooze_petrophysics. + """ phi_a = _arr(phi) return np.asarray(phi_a * hi_fluid + (1.0 - phi_a) * hi_matrix) def phi_from_hi(hi_log: ArrayLike, *, hi_matrix: float, hi_fluid: float = 1.0) -> _Float: - """Porosity from a hydrogen-index log ``phi = (HI - HI_matrix)/(HI_fluid - HI_matrix)``.""" + """Porosity from a hydrogen-index log ``phi = (HI - HI_matrix)/(HI_fluid - HI_matrix)``. + + Sources: src2014_08/article6_siliceous_ooze_petrophysics. + """ return np.asarray((_arr(hi_log) - hi_matrix) / (hi_fluid - hi_matrix)) def phi_hi_correction(phi_apparent: ArrayLike, hi: ArrayLike) -> _Float: - """Hydrogen-index porosity correction ``phi = phi_apparent/HI`` (neutron & NMR).""" + """Hydrogen-index porosity correction ``phi = phi_apparent/HI`` (neutron & NMR). + + Sources: src2017_08/article1_bakken_nmr_relaxometry. + """ return np.asarray(_arr(phi_apparent) / _arr(hi)) def collision_parameter(a_mass: ArrayLike) -> _Float: - """Neutron collision parameter ``alpha = ((A-1)/(A+1))**2``.""" + """Neutron collision parameter ``alpha = ((A-1)/(A+1))**2``. + + Sources: src2014_12/article5_cased_well_gas_saturation. + """ a = _arr(a_mass) return np.asarray(((a - 1.0) / (a + 1.0)) ** 2) @@ -391,6 +571,8 @@ def average_lethargy_gain(a_mass: ArrayLike) -> _Float: """Mean logarithmic energy decrement ``xi = 1 + alpha/(1-alpha)*ln(alpha)``. The hydrogen limit ``A=1`` (``alpha=0``) returns ``xi=1``. + + Sources: src2014_12/article5_cased_well_gas_saturation. """ alpha = collision_parameter(a_mass) safe = np.where(alpha > 0.0, alpha, 1.0) @@ -399,7 +581,10 @@ def average_lethargy_gain(a_mass: ArrayLike) -> _Float: def moderating_power(a_mass: ArrayLike, sigma_s: ArrayLike) -> _Float: - """Moderating power ``xi*Sigma_s`` (slowing-down power).""" + """Moderating power ``xi*Sigma_s`` (slowing-down power). + + Sources: src2014_12/article5_cased_well_gas_saturation. + """ return np.asarray(average_lethargy_gain(a_mass) * _arr(sigma_s)) @@ -448,7 +633,11 @@ def compensated_neutron_porosity( def co_ratio(c_yield: ArrayLike, o_yield: ArrayLike) -> _Float: - """Carbon-oxygen ratio ``COR = Y_C/Y_O``.""" + """Carbon-oxygen ratio ``COR = Y_C/Y_O``. + + Sources: src2020_06/article2_cement_quality_co_pulsed_neutron, + src2020_12/article1_nuclear_spectroscopy_history. + """ return np.asarray(_arr(c_yield) / _arr(o_yield)) @@ -459,7 +648,11 @@ def so_from_co( *, clip: tuple[float, float] | None = (0.0, 1.0), ) -> _Float: - """Oil saturation from C/O endpoint interpolation ``So = (COR-COR_w)/(COR_o-COR_w)``.""" + """Oil saturation from C/O endpoint interpolation ``So = (COR-COR_w)/(COR_o-COR_w)``. + + Sources: src2020_06/article2_cement_quality_co_pulsed_neutron, + src2020_12/article4_co_sigma_saturation_casestudy. + """ so = (_arr(cor) - _arr(cor_water)) / (_arr(cor_oil) - _arr(cor_water)) if clip is not None: so = np.clip(so, clip[0], clip[1]) @@ -482,6 +675,8 @@ def co_forward_3phase( ``C = phi*(So*c_oil + Sg*c_gas) + (1-phi)*c_mat``; ``O = phi*Sw*o_w + (1-phi)*o_mat``. + + Sources: src2023_12/mcglynn_pulsed_neutron. """ phi_a = _arr(phi) carbon = phi_a * (_arr(so) * c_oil + _arr(sg) * c_gas) + (1.0 - phi_a) * c_mat @@ -490,17 +685,27 @@ def co_forward_3phase( def yields_to_weights(fy2w: ArrayLike, s: ArrayLike, y: ArrayLike) -> _Float: - """Elemental weight fraction from a spectroscopy yield ``W = FY2W*S*Y``.""" + """Elemental weight fraction from a spectroscopy yield ``W = FY2W*S*Y``. + + Sources: src2020_12/article2_formation_chlorine_salinity, + src2020_12/article3_self_compensated_spectroscopy. + """ return np.asarray(_arr(fy2w) * _arr(s) * _arr(y)) def weights_to_yields(fy2w: ArrayLike, s: ArrayLike, w: ArrayLike) -> _Float: - """Spectroscopy yield from a weight fraction ``Y = W/(FY2W*S)`` (inverse).""" + """Spectroscopy yield from a weight fraction ``Y = W/(FY2W*S)`` (inverse). + + Sources: src2020_12/article2_formation_chlorine_salinity. + """ return np.asarray(_arr(w) / (_arr(fy2w) * _arr(s))) def toc_from_yield(y_toc: ArrayLike, calib: ArrayLike) -> _Float: - """Total organic carbon from a carbon yield ``TOC = calib*Y_TOC``.""" + """Total organic carbon from a carbon yield ``TOC = calib*Y_TOC``. + + Sources: src2014_06/article2_borehole_carbon_toc. + """ return np.asarray(_arr(calib) * _arr(y_toc)) @@ -515,21 +720,33 @@ def counting_precision(counts: ArrayLike) -> _Float: def counting_sigma(value: ArrayLike, counts: ArrayLike) -> _Float: - """Absolute counting uncertainty ``value/sqrt(N)`` (Poisson).""" + """Absolute counting uncertainty ``value/sqrt(N)`` (Poisson). + + Sources: src2014_10/article3_nuclear_density_alternatives. + """ return np.asarray(_arr(value) / np.sqrt(_arr(counts))) def decay_constant(half_life: ArrayLike) -> _Float: - """Radioactive decay constant ``lambda = ln(2)/T_half``.""" + """Radioactive decay constant ``lambda = ln(2)/T_half``. + + Sources: src2015_08/article2_condensed_vapor_gamma. + """ return np.asarray(np.log(2.0) / _arr(half_life)) def radioactive_decay(n0: ArrayLike, t: ArrayLike, half_life: ArrayLike) -> _Float: - """Radioactive decay ``N = N0*exp(-lambda*t)`` with ``lambda = ln(2)/T_half``.""" + """Radioactive decay ``N = N0*exp(-lambda*t)`` with ``lambda = ln(2)/T_half``. + + Sources: src2015_08/article2_condensed_vapor_gamma. + """ lam = decay_constant(half_life) return np.asarray(_arr(n0) * np.exp(-lam * _arr(t))) def activity(n: ArrayLike, half_life: ArrayLike) -> _Float: - """Radioactive activity ``A = lambda*N`` with ``lambda = ln(2)/T_half``.""" + """Radioactive activity ``A = lambda*N`` with ``lambda = ln(2)/T_half``. + + Sources: src2015_08/article2_condensed_vapor_gamma. + """ return np.asarray(decay_constant(half_life) * _arr(n)) diff --git a/petrolib/porosity_lithology.py b/petrolib/porosity_lithology.py index c6e1d64..6cd0858 100644 --- a/petrolib/porosity_lithology.py +++ b/petrolib/porosity_lithology.py @@ -33,6 +33,186 @@ saturations v/v fractions, GR in API, resistivity ohm-m, TOC in the unit each function's docstring states. numpy-broadcastable; scipy is imported lazily only by the nnls mineral solver. + +References +---------- +Complete citations for the source tags used in this module (SPWLA journal +*Petrophysics*): + +src2014_06/article1 -- Article 1: A Case Study about Formation Evaluation and Rock Physics Modeling + of the Bazhenov Shale. Pavel Kulyapin and Tatiana F. Sokolova (2014). Petrophysics Vol. 55, No. 3 + (June 2014), pp. 211-218. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2014_08/article3 -- Article 3: Multiphase Flow in Porous Rock Imaged Under Dynamic Flow + Conditions with Fast X-Ray Computed Microtomography S. Berg, R. Armstrong, H. Ott, A. Georgiadis, + S. A. Klapp, A. Schwing, R. Neiteler, N. Brussee, A. Makurat, L. Leu, F. Enzmann, J.-O. Schwarz, + M. Wolf, F. Khan, M. Kersten, S. Irvine, M. Stampanoni (2014). Petrophysics Vol. 55, No. 4 + (August 2014), pp. 304-312. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2014_10/article2 -- Article 2: Application and Quality Control of Core Data for the Development + and Validation of Elemental Spectroscopy Log Interpretation Susan Herron, Michael Herron, Iain + Pirie, Pablo Saldungaray, Paul Craddock, Alyssa Charsky, Marina Polyakov, Frank Shray, Ting Li + (2014). Petrophysics Vol. 55, No. 5 (October 2014), pp. 392-414. DOI: none assigned (this issue + predates SPWLA DOI assignment). +src2014_12/article1 -- Article 1: Review of Existing Shaly-Sand Models and Introduction of a New + Method Based on Dry-Clay Parameters. Max Peeters and Antony Holmes (2014). Petrophysics Vol. 55, + No. 6 (December 2014), pp. 543-553. DOI: none assigned (this issue predates SPWLA DOI + assignment). +src2015_02/article5 -- Article 5: Recharacterization and Validation of Through-the-Bit-Logging Tool + Measurements. Slocombe, Bammi, Hunka, Reischman, Schmid (2015). Petrophysics Vol. 56, No. 1 + (February 2015), pp. 58-71. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2015_06/article1 -- Article 1: Improvement in Heavy-Oil Reservoir Evaluation Using Nuclear + Magnetic Resonance: Long Lake and Kinosis SAGD Projects, Alberta, Canada. Cheng, Kotov, Pyke, + Hanif (2015). Petrophysics Vol. 56, No. 3 (June 2015), pp. 239-250. DOI: none assigned (this + issue predates SPWLA DOI assignment). +src2015_08/article4 -- Article 4: Petrophysical Interpretation of LWD, Neutron-Induced Gamma-Ray + Spectroscopy Measurements: An Inversion-Based Approach. Ajayi, Torres-Verdin, Preeg (2015). + Petrophysics Vol. 56, No. 4 (August 2015), pp. 358-378. DOI: none assigned (this issue predates + SPWLA DOI assignment). +src2015_10/article3 -- Article 3: Using Advanced Logging Measurements to Develop a Robust + Petrophysical Model for the Bakken Petroleum System. Simpson, Hohman, Pirie, Horkowitz (2015). + Petrophysics Vol. 56, No. 5 (October 2015), pp. 457-478. DOI: none assigned (this issue predates + SPWLA DOI assignment). +src2015_10/article6 -- Article 6: Applying a Consistent Evaluation Approach to Thin-Bedded Sands in + a Gulf of Mexico Deepwater Field. Salunke, Hamman (2015). Petrophysics Vol. 56, No. 5 (October + 2015), pp. 511-520. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2015_12/article3 -- Article 3: Petrophysical Characterization of Bitumen-Saturated Karsted + Carbonates: Case Study of the Multibillion Barrel Upper Devonian Grosmont Formation, Northern + Alberta, Canada. MacNeil (2015). Petrophysics Vol. 56, No. 6 (December 2015), pp. 592-614. DOI: + none assigned (this issue predates SPWLA DOI assignment). +src2016_04/article2 -- Article 2: Integrated Petrofacies Characterization and Interpretation of + Depositional Environment of the Bakken Shale in the Williston Basin, North America. Bhattacharya, + Carr (2016). Petrophysics Vol. 57, No. 2 (April 2016), pp. 96-111. DOI: none assigned (this issue + predates SPWLA DOI assignment). +src2016_04/article3 -- Article 3: A New Approach to Measuring Organic Density. Dang, Sondergeld, + Rai (2016). Petrophysics Vol. 57, No. 2 (April 2016), pp. 112-120. DOI: none assigned (this issue + predates SPWLA DOI assignment). +src2016_10/article3 -- Article 3: On Error Calculation and Use of First-Order Error Propagation as + Integral Part of Petrophysical Calculation. Stalheim (2016). Petrophysics Vol. 57, No. 5 (October + 2016), pp. 465-478. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2017_04/article2 -- Article 2: Characterizing Hydrocarbon Storage in Organic-Rich Mudstones by + Integrating Core Measurements, Kinetic Modeling, and Pore-Scale Observations: Application to + South Texas Organic-Rich Mudstones. Capsan, Sanchez-Ramirez (2017). Petrophysics Vol. 58, No. 2 + (April 2017), pp. 97-115. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2017_06/article6 -- Article 6: A Case Study on Integrated Petrophysical Characterization of a + Carbonate Reservoir Pore System in the Offshore Red River Basin of Vietnam. Giao, Chung (2017). + Petrophysics Vol. 58, No. 3 (June 2017), pp. 289-301. DOI: none assigned (this issue predates + SPWLA DOI assignment). +src2017_10/article4 -- Article 4: Imaging Near-Wellbore Petrophysical Properties by Joint Inversion + of Sonic, Resistivity, and Density Logging Data. Shetty, Liang, Simoes, Canesin, Boyd, Zeroug, + Sinha, Habashy, Domingues, Amorim, Abbots (2017). Petrophysics Vol. 58, No. 5 (October 2017), pp. + 501-516. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2017_10/article5 -- Article 5: Lessons Learned in Permian Core Analysis: Comparison Between + Retort, GRI, and Routine Methodologies. Blount, Croft, Driskill, Tepper (2017). Petrophysics Vol. + 58, No. 5 (October 2017), pp. 517-527. DOI: none assigned (this issue predates SPWLA DOI + assignment). +src2017_12/article4 -- Article 4: 3D Printing Berea Sandstone: Testing a New Tool for Petrophysical + Analysis of Reservoirs. Ishutov, Hasiuk (2017). Petrophysics Vol. 58, No. 6 (December 2017), pp. + 592-602. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2017_12/article5 -- Article 5: Experimental Quantification of the Impact of Thermal Maturity on + Kerogen Density. Jagadisan, Yang, Heidari (2017). Petrophysics Vol. 58, No. 6 (December 2017), + pp. 603-612. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2017_12/article6 -- Article 6: Impact of Different Cleaning Methods on Petrophysical + Measurements. Gupta, Rai, Tinni, Sondergeld (2017). Petrophysics Vol. 58, No. 6 (December 2017), + pp. 613-622. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2018_04/article2 -- Article 2: The Problem With Silt in Low-Resistivity Low-Contrast (LRLC) Pay + Reservoirs. Belevich, Bal (2018). DOI: 10.30632/PJV59N2-2018a1. Petrophysics Vol. 59 No. 2 (Apr + 2018). +src2018_06/article2 -- Article 2: Matrix-Adjusted Shale Porosity Measured in Horizontal Wells. + Craddock, Mosse, Bernhardt, Ortiz, Gonzalez Tomassini, Pirie, Saldungaray, Pomerantz (2018). DOI: + 10.30632/PJV59N3-2018a1. Petrophysics Vol. 59 No. 3 (Jun 2018). +src2018_10/article3 -- Article 3: Integrating Measured Kerogen Properties With Log Analysis for + Petrophysics and Geomechanics in Unconventional Resources. Craddock, Mosse, Prioul, Miles, Loan, + Pirie, Rylander, Lewis, Pomerantz (2018). DOI: 10.30632/PJV59N5-2018a2. +src2018_10/article9 -- Article 9: Upscaling of Digital Rock Porosities by Correlation With Whole- + Core CT-Scan Histograms. Hertel, Rydzy, Anger, Berg, Appel, de Jong (2018). DOI: + 10.30632/PJV59N5-2018a8. Petrophysics Vol. 59 No. 5 (Oct 2018) - "Best of 2018 SPWLA Symposium" + issue. +src2019_02/article2 -- Article 2: Defining Net-Pay Cutoffs in Carbonates Using Advanced + Petrophysical Methods. Skalinski, Mallan, Edwards, Sun, Toumelin, Kelly, Wushur, Sullivan (2019). + DOI: 10.30632/PJV60N1Y2019a1. Petrophysics Vol. 60 No. 1 (Feb 2019). +src2019_04/article1 -- Article 1 (Tutorial): Organic Mudstone Petrophysics, Part 2: Workflow to + Estimate Storage Capacity. Newsham, Comisky, Chemali (2019). DOI: 10.30632/PJV60N2-2019t1. +src2019_06/article1 -- Article 1 (Tutorial): Organic-Mudstone Petrophysics: Part 3: Workflow to + Estimate Storage Capacity. Newsham, Comisky, Chemali (2019). DOI: 10.30632/PJV60N3-2019t1. +src2019_08/article2 -- Article 2: Total Organic Carbon Characterization Using Neural-Network + Analysis of XRF Data. Lawal, Mahmoud, Alade, Abdulraheem (2019). DOI: 10.30632/PJV60N4-2019a2. + Petrophysics Vol. 60 No. 4 (Aug 2019). +src2019_10/article1 -- Article 1: Thermal Maturity-Adjusted Log Interpretation (TMALI) in Organic + Shales. Craddock, Miles, Lewis, Pomerantz (2019). DOI: 10.30632/PJV60N5-2019a1. Petrophysics Vol. + 60 No. 5 (Oct 2019). +src2019_10/article6 -- Article 6: Experimental Method for Time-Lapse Micro-CT Imaging of Mud- + Filtrate Invasion and Mudcake Deposition. Schroeder, Torres-Verdin (2019). DOI: + 10.30632/PJV60N5-2019a6. Petrophysics Vol. 60 No. 5 (Oct 2019). +src2019_12/article4 -- Article 4: Crushed-Rock Analysis Workflow Based on Advanced Fluid + Characterization for Improved Interpretation of Core Data. Nikitin, Durand, McMullen, Blount, + Driskill, Hows (2019). DOI: 10.30632/PJV60N6-2019a4. Petrophysics Vol. 60 No. 6 (Dec 2019). +src2020_02/article6 -- Article 6: Untangle Shale and Gas Effects to Estimate Porosity and Net/Gross + Ratio Using a Boomerang Workflow - A Case Study in Shoreface Reservoirs in Brunei. Xu, Sharif + (2020). DOI: 10.30632/PJV61N1-2020a5. Petrophysics Vol. 61 No. 1 (Feb 2020). +src2020_12/article5 -- Article 5: Integration of Nuclear Spectroscopy Technology and Core Data + Results for Through-Casing TOC Measurement and Saturation Analysis - A Case Study in Najmah- + Sargelu Reservoir, South Kuwait. Bouchou, Abughneej, Ghioca, Alarcon, Mendez (2020). DOI: + 10.30632/PJV61N6-2020a5. Petrophysics Vol. 61 No. 6 (Dec 2020). +src2021_02/article1 -- Article 1 (Tutorial): Maximizing Value From Mudlogs - Integrated Approach to + Determine Net Pay. Malik, Hanson, Clinch (2021). DOI: 10.30632/PJV62N1-2021t1. Petrophysics Vol. + 62 No. 1 (Feb 2021). +src2021_10/article4 -- Article 4: 3D Printing Mudrocks: Experiments in Validating Clay as a Build + Material for 3D Printing Porous Micromodels. Hasiuk, Harding (2021). DOI: + 10.30632/PJV62N5-2021a4. Petrophysics Vol. 62 No. 5 (Oct 2021). +src2021_12/article02 -- Article 2: Enhanced Mineral Quantification and Uncertainty Analysis From + Downhole Spectroscopy Logs Using Variational Autoencoders. Craddock, Srivastava, Datir, Rose, + Zhou, Mosse, Venkataramanan (2021). DOI: 10.30632/PJV62N6-2021a2. Petrophysics Vol. 62 No. 6 (Dec + 2021). +src2021_12/article09 -- Article 9: An Integrated Petrophysical Characterization of a Siliciclastic + Tight Gas Reservoir in Neuquen Basin, Western Argentina. Carrizo, Santiago, Saldungaray (2021). + DOI: 10.30632/PJV62N6-2021a9. Petrophysics Vol. 62 No. 6 (Dec 2021). +src2022_02/article5 -- Article 5: Evaluating Petrophysical Properties and Volumetrics Uncertainties + of Sand Injectite Reservoirs - Norwegian North Sea. Kotwicki, Baig, Johansen, Leirdal, Aftret, + Sandstad, Anthonsen, Gianotten, Hansen, Firinu (2022). DOI: 10.30632/PJV63N1-2022a5. Petrophysics + Vol. 63 No. 1 (Feb 2022). +src2022_02/article6 -- Article 6: Investigating Delaware Basin Bone Spring and Wolfcamp + Observations Through Core-Based Quantification: Case Study in the Integrated Workflow, Including + Closed Retort Comparisons. Perry, Zumberge, Cheng (2022). DOI: 10.30632/PJV63N1-2022a6. + Petrophysics Vol. 63 No. 1 (Feb 2022). +src2022_04/article7 -- Article 7: Application of Digital Core Technology in Wellbore Stability + Research. Zhou, Ye, Zhu, Cheng, Song, Wang, Cai (2022). DOI: 10.30632/PJV63N2-2022a7. + Petrophysics Vol. 63 No. 2 (Apr 2022). +src2022_08/article4 -- Article 4: A Fast and Transparent Bayesian Log Interpretation Method. + Spalburg (2022). DOI: 10.30632/PJV63N4-2022a4. Petrophysics Vol. 63 No. 4 (Aug 2022). +src2022_12/article7 -- Article 7: Using Digital Rock Physics to Evaluate Novel Percussion Core + Quality. Lakshtanov, Zapata, Saucier, Cook, Eve, Lancaster, Lane, Gettemy, Sincock, Liu, Geetan, + Draper, Gill (2022). DOI: 10.30632/PJV63N6-2022a7. Petrophysics Vol. 63 No. 6 (Dec 2022) — Best + Papers of the 2022 SPWLA Annual Symposium special issue. +src2023_02/article4 -- Article 4: First Hexa-Combo Logging-While-Drilling Run in Kuwait: A Case + Study. Saleh, Al-Khudari, Al-Azmi, Al-Otaibi, Patnaik, Joshi, Abdulkarim, Aki, Fahri, Sanyal, + Sainuddin (2023). DOI: 10.30632/PJV64N1-2023a4. Petrophysics Vol. 64 No. 1 (Feb 2023). +src2023_02/article6 -- Article 6: Enhancing the Detectability of Deep-Sensing Borehole EM + Instruments by Joint Inversion of Multiple Logs Within a Probabilistic Geosteering Workflow. + Jahani, Alyaev, Ambia, Fossum, Suter, Torres-Verdín (2023). DOI: 10.30632/PJV64N1-2023a6. + Petrophysics Vol. 64 No. 1 (Feb 2023). +src2023_06/article8 -- Eichmann, S.L., Bouchard, J., Ow, H., Petkie, D., Poitzsch, M.E. "THz + Imaging to Map the Lateral Microporosity Distribution in Carbonate Rocks" Petrophysics, Vol. 64, + No. 3 (June 2023), pp. 438-447 DOI: 10.30632/PJV64N3-2023a8. +src2023_08/article1 -- Fitz, D.E. (2023). "Evolution of Casedhole Nuclear Surveillance Logging + Through Time", Petrophysics, Vol. 64, No. 4 (August 2023), pp. 473-501. DOI: + 10.30632/PJV64N4-2023a1. +src2023_08/article3 -- Jácomo, M.H., Hartmann, G.A., Rebelo, T.B., Mattos, N.H., Batezelli, A., + Leite, E.P. (2023). "Mineralogical Modeling and Petrophysical Properties of the Barra Velha + Formation, Santos Basin, Brazil", Petrophysics, Vol. 64, No. 4, pp. 518-543. DOI: + 10.30632/PJV64N4-2023a3. +src2025_06/toc_prediction -- Comparative Analysis of TOC Logging Evaluation Methods Using Machine + Learning Implements the methodology from: Dong, M., Shang, J., Tian, L., Wu, M., and Nie, X., + 2025, "Comparative Analysis of TOC Logging Evaluation Methods Using Machine Learning – A Case + Study of the Ordos Basin-Yanchang Formation," Petrophysics, Vol. 66, No. 3, pp. 425–448. +src2025_10/a3 -- Article 3: An Efficient Approach for Predicting Young's Modulus of Sandstones + Using Well Logs Without Shear-Wave Traveltime Authors: Mabkhout M. Al-Dousari, Yousef M. Al- + Enezi, Ali A. Garrouch Ref: Petrophysics, Vol. 66, No. 5 (October 2025), pp. 741-762. DOI: + 10.30632/PJV66N5-2025a3. +src2025_10/a6 -- Article 6: Enhanced Learning Experience for New Petrophysicists Using Open-Source + Carbonate Data and Python Programming Author: Imran M. Fadhil Ref: Petrophysics, Vol. 66, No. 5 + (October 2025), pp. 807-838. DOI: 10.30632/PJV66N5-2025a6. +src2026_04/a03 -- Zhao, Y. (2026). Effect of Water-Rock Interactions on Mechanical Properties and + Acoustic Emission Characteristics of Sandstones. Petrophysics, 67(2), 280–293. DOI: + 10.30632/PJV67N2-2026a3. """ from __future__ import annotations diff --git a/petrolib/relperm_wettability.py b/petrolib/relperm_wettability.py index c276c64..e00ad9a 100644 --- a/petrolib/relperm_wettability.py +++ b/petrolib/relperm_wettability.py @@ -31,6 +31,122 @@ Saturations and relative permeabilities are fractions; viscosities in Pa*s (any consistent unit cancels in ratios). numpy-only at import; :func:`fit_corey` imports scipy lazily. + +References +---------- +Complete citations for the source tags used in this module (SPWLA journal +*Petrophysics*): + +src2014_02/article3 -- Article 3: An Evaluation of Spontaneous Imbibition of Water into Oil-Wet + Carbonate Reservoir Cores Using Nanofluid. Abbas Roustaei (2014). Petrophysics Vol. 55, No. 1 + (February 2014), pp. 31-37. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2014_08 -- Petrophysics Vol. 55 No. 4 (Aug 2014) (issue-level reference). +src2014_08/article1 -- Article 1: Drainage Three-Phase Flow Relative Permeability on Oil-Wet + Carbonate Reservoir Rock Types: Experiments, Interpretation and Comparison with Standard + Correlations. P. Egermann, K. Mejdoub, J.-M. Lombard, O. Vizika, Z. Kalam (2014). Petrophysics + Vol. 55, No. 4 (August 2014), pp. 287-293. DOI: none assigned (this issue predates SPWLA DOI + assignment). +src2014_08/article4 -- Article 4: Impact of Wettability on Residual Oil Saturation and Capillary + Desaturation Curves K. J. Humphry, B. M. J. M. Suijkerbuijk, H. A. van der Linde, S. G. J. + Pieterse, S. K. Masalmeh (2014). Petrophysics Vol. 55, No. 4 (August 2014), pp. 313-318. DOI: + none assigned (this issue predates SPWLA DOI assignment). +src2014_12/article3 -- Article 3: Experimental Study of the Effects of Wettability and Fluid + Saturation on NMR and Dielectric Measurements in Limestone Lalitha Venkataramanan, Martin D. + Hurlimann, Jeffrey A. Tarvin, Kamilla Fellah, Diana Acero-Allard, Nikita V. Seleznev (2014). + Petrophysics Vol. 55, No. 6 (December 2014), pp. 572-586. DOI: none assigned (this issue predates + SPWLA DOI assignment). +src2016_02 -- Petrophysics Vol. 57 No. 1 (Feb 2016) (issue-level reference). +src2016_02/article1 -- Article 1: The Impact of Reservoir Conditions and Rock Heterogeneity on + CO2-Brine Multiphase Flow in Permeable Sandstone. Krevor, Reynolds, Al-Menhali, Niu (2016). + Petrophysics Vol. 57, No. 1 (February 2016), pp. 12-18. DOI: none assigned (this issue predates + SPWLA DOI assignment). +src2016_02/article4 -- Article 4: Low-Salinity Waterflooding: Facts, Inconsistencies and the Way + Forward. Hamon (2016). Petrophysics Vol. 57, No. 1 (February 2016), pp. 41-50. DOI: none assigned + (this issue predates SPWLA DOI assignment). +src2016_06/article3 -- Article 3: Permeability Interpretation from Wireline Formation Testing + Measurements with Consideration of Effective Thickness. Yang, Yang (2016). Petrophysics Vol. 57, + No. 3 (June 2016), pp. 251-269. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2016_10/article2 -- Article 2: How Pore-Scale Attributes May Be Used to Derive Robust Drainage + and Imbibition Water-Saturation Models in Complex Tight-Gas Reservoirs. Merletti, Gramin, + Salunke, Hamman, Spain, Shabro, Armitage, Torres-Verdin, Salter, Dacy (2016). Petrophysics Vol. + 57, No. 5 (October 2016), pp. 447-464. DOI: none assigned (this issue predates SPWLA DOI + assignment). +src2017_02 -- Petrophysics Vol. 58 No. 1 (Feb 2017) (issue-level reference). +src2017_02/article1 -- Article 1: Flow Regimes During Immiscible Displacement. Armstrong, McClure, + Berrill, Rucker, Schluter, Berg (2017). Petrophysics Vol. 58, No. 1 (February 2017), pp. 10-18. + DOI: none assigned (this issue predates SPWLA DOI assignment). +src2017_02/article5 -- Article 5: Comparison of Four Numerical Simulators for SCAL Experiments. + Lenormand, Lorentzen, Maas, Ruth (2017). Petrophysics Vol. 58, No. 1 (February 2017), pp. 48-56. + DOI: none assigned (this issue predates SPWLA DOI assignment). +src2018_02/article5 -- Article 5: Using Digital Rock Technology to Quality Control and Reduce + Uncertainty in Relative Permeability Measurements. Schembre-McCabe, Kamath (2018). DOI: + 10.30632/petro_059_1_a4. Petrophysics Vol. 59 No. 1 (Feb 2018). +src2018_02/article8 -- Article 8: Application of an Optimization Method for the Restoration of Core + Samples for SCAL Experiments. Sripal, James (2018). DOI: 10.30632/petro_059_1_a7. Petrophysics + Vol. 59 No. 1 (Feb 2018). +src2018_04/article9 -- Article 9: Downhole Estimation of Relative Permeability With Integration of + Formation-Tester Measurements and Advanced Well Logs. Hadibeik, Azari, Kalawina, Ramakrishna, + Eyuboglu, Khan, Al-Rushaid, Al-Rashidi, Ahmad (2018). DOI: 10.30632/PJV59N2-2018a8 (inferred; + body beyond extraction). Petrophysics Vol. 59 No. 2 (Apr 2018). +src2018_06/article3 -- Article 3: Water-Wet or Oil-Wet: is it Really That Simple in Shales?. Gupta, + Jernigen, Curtis, Rai, Sondergeld (2018). DOI: 10.30632/PJV59N3-2018a2. Petrophysics Vol. 59 No. + 3 (Jun 2018). +src2019_02/article1 -- Article 1 (Tutorial): Organic-Mudstone Petrophysics: Workflow to Estimate + Storage Capacity (Part 1). Newsham, Comisky, Chemali (2019). DOI: 10.30632/PJV60N1Y2019t1. +src2019_04/article11 -- Article 11: Loading Effects on Gas Relative Permeability of a Low- + Permeability Sandstone. Agostini, Egermann, Jeannin, Portier, Skoczylas, Wang (2019). DOI: + 10.30632/PJV60N2-2019a9. Petrophysics Vol. 60 No. 2 (Apr 2019). +src2019_04/article3 -- Article 3: Pore-Scale Insights on Trapped Oil During Waterflooding of + Sandstone Rocks of Varying Wettability States. Berthet, Hebert, Barbouteau, Andriamananjaona, + Rivenq (2019). DOI: 10.30632/PJV60N2-2019a1. Petrophysics Vol. 60 No. 2 (Apr 2019). +src2019_08/article4 -- Article 4: Practical Approach to Derive Wettability Index by NMR in Core + Analysis Experiments. Looyestijn (2019). DOI: 10.30632/PJV60N4-2019a4. Petrophysics Vol. 60 No. 4 + (Aug 2019). +src2019_08/article6 -- Article 6: Novel Coupling Smart Water-CO2 Flooding for Sandstone Reservoirs. + Al-Saedi, Flori (2019). DOI: 10.30632/PJV60N4-2019a6. Petrophysics Vol. 60 No. 4 (Aug 2019). +src2020_04/article5 -- Article 5: Workflow for Upscaling Wettability From the Nanoscale to Core + Scale. Rucker, Bartels, Bultreys, Boone, Singh, Garfi, Scanziani, Spurin, Yesufu-Rufai, Krevor, + Blunt, Wilson, Mahani, Cnudde, Luckham, Georgiadis, Berg (2020). DOI: 10.30632/PJV61N2-2020a5. + Petrophysics Vol. 61 No. 2 (Apr 2020). +src2020_04/article6 -- Article 6: Estimation of Gas-Condensate Relative Permeability Using a + Lattice Boltzmann Modeling Approach. Schembre-McCabe, Kamath, Fager, Crouse (2020). DOI: + 10.30632/PJV61N2-2020a6. Petrophysics Vol. 61 No. 2 (Apr 2020). +src2020_04/article7 -- Article 7: Effect of Injection Pressure on the Imbibition Relative + Permeability and Capillary Pressure Curves of Shale Gas Matrix. Al-Ameri, Mazeel (2020). DOI: + 10.30632/PJV61N2-2020a7. Petrophysics Vol. 61 No. 2 (Apr 2020). +src2020_06/article4 -- Article 4: Evaluation of Relative Permeability From Resistivity Data for + Fractal Porous Media. Shi, Meng, Liu, Zhang, Wang (2020). DOI: 10.30632/PJV61N3-2020a4. + Petrophysics Vol. 61 No. 3 (Jun 2020). +src2021_10/article2 -- Article 2: Enhanced Learning of Fundamental Petrophysical Concepts Through + Image Processing and 3D Printing. Alyafei, Al Musleh, Bautista, Idris, Seers (2021). DOI: + 10.30632/PJV62N5-2021a2. Petrophysics Vol. 62 No. 5 (Oct 2021). +src2022_06/article9 -- Article 9: NMR-Based Wettability Index for Unconventional Rocks. Dick, + Veselinovic, Bonnie, Kelly (2022). DOI: 10.30632/PJV63N3-2022a9. Petrophysics Vol. 63 No. 3 (Jun + 2022) — NMR SIG Special Issue. +src2022_10/article4 -- Article 4: Mud-Filtrate Invasion in Laminated and Spatially Heterogeneous + Rocks: High-Resolution In-Situ Visualization and Analysis Using Time-Lapse X-Ray Microcomputed + Tomography (Micro-CT). Schroeder, Torres-Verdin (2022). DOI: 10.30632/PJV63N5-2022a4. + Petrophysics Vol. 63 No. 5 (Oct 2022). +src2023_06/article4 -- Gao, Y., Sorop, T., Brussee, N., van der Linde, H., Coorn, A., Appel, M., + Berg, S. "Advanced Digital-SCAL Measurements of Gas Trapped in Sandstone" Petrophysics, Vol. 64, + No. 3 (June 2023), pp. 368-383 DOI: 10.30632/PJV64N3-2023a4. +src2024_04 -- Petrophysics Vol. 65 No. 2 (Apr 2024) (issue-level reference). +src2024_10 -- Petrophysics Vol. 65 No. 5 (Oct 2024) (issue-level reference). +src2025_02 -- Petrophysics Vol. 66 No. 1 (Feb 2025) (issue-level reference). +src2025_02/co2_brine_relperm -- CO2/Brine Relative Permeability: Reconciling SS and USS Methods. + Mascle et al., 2025, Petrophysics 66(1), 26-43. DOI:10.30632/PJV66N1-2025a2. +src2025_02/dopant_impact_scal -- Impact of Dopants (NaI) on SCAL Experiments. Pairoys et al., 2025, + Petrophysics 66(1), 123-133. DOI:10.30632/PJV66N1-2025a9. +src2025_02/enhanced_gas_recovery -- Enhanced Gas Recovery (EGR) by CO2 Injection. Jones et al., + 2025, Petrophysics 66(1), 54-66. DOI:10.30632/PJV66N1-2025a4. +src2025_02/scal_model_ccs -- SCAL Model for CCS: LET Correlations for Relative Permeability and + Capillary Pressure. Ebeltoft et al., 2025, Petrophysics 66(1), 10-25. + DOI:10.30632/PJV66N1-2025a1. +src2025_12/analog_kr -- Analog Two-Phase Relative Permeability for CO₂/Brine Estimation. + Petrophysics, 66(6), 969–981. DOI: 10.30632/PJV66N6-2025a4. +src2026_04/a02 -- Aljishi, M.K., Chitrala, Y., Dang, S.T., and Rai, C. (2026). Wettability-Based + Pore Partitioning and Its Effects on Oil Recovery and Formation Damage in Unconventional + Reservoirs. Petrophysics, 67(2), 263–279. DOI: 10.30632/PJV67N2-2026a2. """ from __future__ import annotations diff --git a/petrolib/saturation_resistivity.py b/petrolib/saturation_resistivity.py index 0859220..da28247 100644 --- a/petrolib/saturation_resistivity.py +++ b/petrolib/saturation_resistivity.py @@ -33,6 +33,80 @@ consistent pair — the equations are ratio-based); ``phi`` and saturations as fractions; ``qv`` in meq/ml (= meq/cm3); ``cec`` in meq/g; densities in g/cm3. + +References +---------- +Complete citations for the source tags used in this module (SPWLA journal +*Petrophysics*): + +src2014_02/article1 -- Article 1: Solving Complex Dual-Water Equation using Dielectric-NMR- + Spectroscopy and Conventional Logs. Willy Tan, Ryan Lafferty, Thomas J. Neville (2014). + Petrophysics Vol. 55, No. 1 (February 2014), pp. 14-23. DOI: none assigned (this issue predates + SPWLA DOI assignment). +src2014_02/article2 -- Article 2: Capillary Pressure and Resistivity Index Measurements in a Mixed- + Wet Carbonate Reservoir Moustafa R. Dernaika, Mohamed S. Efnik, Safouh Koronfol, Svein M. + Skjaeveland, Maisoon M. Al Mansoori, Hafez Hafez, Mohammed Z. Kalam (2014). Petrophysics Vol. 55, + No. 1 (February 2014), pp. 24-30. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2014_12/article1 -- Article 1: Review of Existing Shaly-Sand Models and Introduction of a New + Method Based on Dry-Clay Parameters. Max Peeters and Antony Holmes (2014). Petrophysics Vol. 55, + No. 6 (December 2014), pp. 543-553. DOI: none assigned (this issue predates SPWLA DOI + assignment). +src2015_06/article4 -- Article 4 (Technical Note): The Bateman-Konen Resistivity-Salinity + Transform. Kennedy (2015). Petrophysics Vol. 56, No. 3 (June 2015), pp. 282-283. DOI: none + assigned (this issue predates SPWLA DOI assignment). +src2015_08 -- Petrophysics Vol. 56 No. 4 (Aug 2015) (issue-level reference). +src2015_12/article4 -- Article 4: Petrophysical Challenges in Giant Carbonate Tengiz Field, + Republic of Kazakhstan. Skalinski, Se, Playton, Theologou, Narr, Sullivan, Mallan (2015). + Petrophysics Vol. 56, No. 6 (December 2015), pp. 615-647. DOI: none assigned (this issue predates + SPWLA DOI assignment). +src2016_02/article5 -- Article 5: Graphical Solutions for Laminated and Dispersed Shaly Sands. + Bootle (2016). Petrophysics Vol. 57, No. 1 (February 2016), pp. 51-59. DOI: none assigned (this + issue predates SPWLA DOI assignment). +src2016_08/article3 -- Article 3: Drainage Capillary Pressure and Resistivity Index from Short-Wait + Porous-Plate Experiments. Dernaika, Wilson, Skjaeveland, Ebeltoft (2016). Petrophysics Vol. 57, + No. 4 (August 2016), pp. 369-376. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2017_10/article1 -- Article 1: Improved Assessment of Hydrocarbon Saturation in Mixed-Wet Rocks + With Complex Pore Structure. Garcia, Heidari, Rostami (2017). Petrophysics Vol. 58, No. 5 + (October 2017), pp. 454-469. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2018_06/article4 -- Article 4: A New Resistivity-Based Model for Improved Hydrocarbon Saturation + Assessment in Clay-Rich Formations Using Quantitative Geometry of the Clay Network. Garcia, + Jagadisan, Rostami, Heidari (2018). DOI: 10.30632/PJV59N3-2018a3. Petrophysics Vol. 59 No. 3 (Jun + 2018). +src2018_10/article2 -- Article 2: A Novel X-Ray Tool for True Sourceless Density Logging. Simon, + Tkabladze, Beekman, Atobatele, De Looz, Grover, Hamichi, Jundt, McFarland, Mlcak, Reijonen, + Revol, Stewart, Yeboah, Zhang (2018). DOI: 10.30632/PJV59N5-2018a1. Petrophysics Vol. 59 No. 5 + (Oct 2018) - "Best of 2018 SPWLA Symposium" issue. +src2019_02/article1 -- Article 1 (Tutorial): Organic-Mudstone Petrophysics: Workflow to Estimate + Storage Capacity (Part 1). Newsham, Comisky, Chemali (2019). DOI: 10.30632/PJV60N1Y2019t1. +src2019_04/article2 -- Article 2 (Tutorial): Introduction to Resistivity Principles for Formation + Evaluation: A Tutorial Primer. Kennedy, Garcia (2019). DOI: 10.30632/PJV60N2-2019t2. Petrophysics + Vol. 60 No. 2 (Apr 2019). +src2020_08 -- Petrophysics Vol. 61 No. 4 (Aug 2020) (issue-level reference). +src2020_10 -- Petrophysics Vol. 61 No. 5 (Oct 2020) (issue-level reference). +src2021_10 -- Petrophysics Vol. 62 No. 5 (Oct 2021) (issue-level reference). +src2021_12 -- Petrophysics Vol. 62 No. 6 (Dec 2021) (issue-level reference). +src2021_12/article10 -- Article 10: Enhanced Assessment of Fluid Saturation in the Wolfcamp + Formation of the Permian Basin. Dash, Heidari (2021). DOI: 10.30632/PJV62N6-2021a10. Petrophysics + Vol. 62 No. 6 (Dec 2021). +src2022_02/article5 -- Article 5: Evaluating Petrophysical Properties and Volumetrics Uncertainties + of Sand Injectite Reservoirs - Norwegian North Sea. Kotwicki, Baig, Johansen, Leirdal, Aftret, + Sandstad, Anthonsen, Gianotten, Hansen, Firinu (2022). DOI: 10.30632/PJV63N1-2022a5. Petrophysics + Vol. 63 No. 1 (Feb 2022). +src2022_04/article6 -- Article 6: Rock Physics Modeling of Gas Hydrate Reservoirs Through + Integrated Core and Well-Log Data in NGHP-02 Area, KG Offshore Basin, India. Kumar, Mishra, + Chatterjee, Tiwari, Avadhani (2022). DOI: 10.30632/PJV63N2-2022a6. Petrophysics Vol. 63 No. 2 + (Apr 2022). +src2024_10 -- Petrophysics Vol. 65 No. 5 (Oct 2024) (issue-level reference). +src2024_10/water_saturation_equations -- Water Saturation Equations for Unconsolidated Reservoirs. + Based on: Acosta et al. (2024), "Unveiling the Optimal Water Saturation Equation for + Unconsolidated Reservoirs: A Case Study From the Tambaredjo Oil Field, Suriname", Petrophysics, + Vol. 65, No. 5, pp. 739-764. +src2024_12 -- Petrophysics Vol. 65 No. 6 (Dec 2024) (issue-level reference). +src2025_10/a6 -- Article 6: Enhanced Learning Experience for New Petrophysicists Using Open-Source + Carbonate Data and Python Programming Author: Imran M. Fadhil Ref: Petrophysics, Vol. 66, No. 5 + (October 2025), pp. 807-838. DOI: 10.30632/PJV66N5-2025a6. +src2025_12 -- Petrophysics Vol. 66 No. 6 (Dec 2025) — Best Papers of the 2024 SCA International + Symposium (issue-level reference). """ from __future__ import annotations diff --git a/petrolib/units.py b/petrolib/units.py index 7683bcb..c3648ea 100644 --- a/petrolib/units.py +++ b/petrolib/units.py @@ -13,6 +13,19 @@ Sources: src2014_02/article2 (bar_to_psi/psi_to_bar), src2025_04/gip_porosity (psi_to_mpa), and inline constants in ~16 further modules. + +References +---------- +Complete citations for the source tags used in this module (SPWLA journal +*Petrophysics*): + +src2014_02/article2 -- Article 2: Capillary Pressure and Resistivity Index Measurements in a Mixed- + Wet Carbonate Reservoir Moustafa R. Dernaika, Mohamed S. Efnik, Safouh Koronfol, Svein M. + Skjaeveland, Maisoon M. Al Mansoori, Hafez Hafez, Mohammed Z. Kalam (2014). Petrophysics Vol. 55, + No. 1 (February 2014), pp. 24-30. DOI: none assigned (this issue predates SPWLA DOI assignment). +src2025_04/gip_porosity -- Improved GIP Method for Shale Effective Porosity Through Pressure Decay. + Based on: Jiang et al., "An Improved GIP Method for Measurements of Shale Effective Porosity + Through Pressure Decay", Petrophysics, Vol. 66, No. 2, April 2025, pp. 237–249. """ from __future__ import annotations diff --git a/petrolib/wellbore_geometry.py b/petrolib/wellbore_geometry.py index 60602f2..cb116a6 100644 --- a/petrolib/wellbore_geometry.py +++ b/petrolib/wellbore_geometry.py @@ -10,6 +10,15 @@ in **radians** (that is the form the ratio factor consumes). The horizontal axes are North/East and TVD is positive downward, so a trajectory column order is ``(TVD, North, East)`` throughout. + +References +---------- +Complete citations for the source tags used in this module (SPWLA journal +*Petrophysics*): + +src2019_06/article9_wellbore_positioning_lwd -- Article 9: Wellbore Positioning While Drilling With + LWD Measurements. Poedjono, Nwosu, Martin (2019). DOI: 10.30632/PJV60N3-2019a8. Petrophysics Vol. + 60 No. 3 (Jun 2019). """ from __future__ import annotations @@ -31,6 +40,8 @@ def dogleg_angle(inc1: float, azi1: float, inc2: float, azi2: float) -> float: inclinations ``i`` and azimuths ``a`` supplied in degrees. This is the numerically well-behaved rearrangement of the spherical law of cosines and is clipped to ``[-1, 1]`` before the ``arccos``. + + Sources: src2019_06/article9_wellbore_positioning_lwd. """ i1, a1, i2, a2 = (np.radians(x) for x in (inc1, azi1, inc2, azi2)) cos_dl = np.cos(i2 - i1) - np.sin(i1) * np.sin(i2) * (1.0 - np.cos(a2 - a1)) @@ -43,6 +54,8 @@ def ratio_factor(dogleg_rad: float) -> float: ``dogleg_rad`` is the dogleg angle in radians; for a near-straight step (``DL < 1e-9``) the factor is exactly ``1.0`` (the balanced-tangential limit). + + Sources: src2019_06/article9_wellbore_positioning_lwd. """ if dogleg_rad < 1e-9: return 1.0 @@ -64,6 +77,8 @@ def minimum_curvature_step( ``dE = half (sin i1 sin a1 + sin i2 sin a2)``, ``dTVD = half (cos i1 + cos i2)`` with ``RF`` the :func:`ratio_factor` of the :func:`dogleg_angle`. Angles in degrees, lengths in the units of ``md``. + + Sources: src2019_06/article9_wellbore_positioning_lwd. """ dmd = md2 - md1 dl = dogleg_angle(inc1, azi1, inc2, azi2) @@ -82,6 +97,8 @@ def survey_to_path(md: ArrayLike, inc: ArrayLike, azi: ArrayLike) -> _Float: Integrates :func:`minimum_curvature_step` from the origin ``(0, 0, 0)`` over consecutive stations of a survey given as parallel ``md``/``inc``/``azi`` arrays (degrees). Column order is ``(TVD, North, East)``. + + Sources: src2019_06/article9_wellbore_positioning_lwd. """ md_a = _arr(md) inc_a = _arr(inc)