Add complete source references to petrolib docstrings

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<t0),
     mean(t0<=img<t1), ..., 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]])

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))

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

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