Petrophysics

This section contains documentation for the Petrophysics module. We indicate the reference (Pt-Br) of Freire[1] for the methods used in this module.

Porosity

stoneforge.petrophysics.porosity.density_porosity(rhob, rhom, rhof)

Estimate the porosity from the bulk density log (Schön[2]).

Parameters:

• rhob (array_like) – Bulk density log.

• rhom (float) – Matrix density.

• rhof (float) – Density of the fluid saturating the rock (Usually 1.0 for water and 1.1 for saltwater mud).

Returns:

phid – Total porosity based on bulk density.

Return type:

array_like

stoneforge.petrophysics.porosity.effective_porosity(phi, vsh)

Calculate the effective porosity from the total porosity and shale volume (Schön[2]).

Parameters:

• phi (array_like) – Porosity log

• vsh (array_like) – Shale volume

Returns:

phie – Effective porosity for the aimed interval (more suitable for the bulk density porosity)

Return type:

array_like

stoneforge.petrophysics.porosity.gaymard_porosity(phid, phin)

Estimate the effective porosity using Gaymard and Poupon[3] method.

Parameters:

• phid (array_like) – Density porosity (porosity calculated using density log)

• phin (int, float) – Neutron porosity (porosity calculated using neutron log)

Returns:

phie – Effective porosity using Gaymard-Poupon method

Return type:

array_like

stoneforge.petrophysics.porosity.neutron_density_porosity(phid, phin, squared=False)

Estimate the effective porosity by calculating the mean of Bulk Density porosity and Neutron porosity (Schön[2]).

Parameters:

• phid (array_like) – Effective porosity and shale free for the aimed interval using the bulk density.

• phin (array_like) – Effective porosity from the neutron log for the aimed interval.

• squared (bool, optional) – If True, the porosity is calculated using the square root of the mean of the squares of the two porosities. If False, the porosity is calculated using the mean of the two porosities. Default is False.

Returns:

phie – Effective porosity from the Bulk Density porosity and Neutron porosity mean.

Return type:

array_like

stoneforge.petrophysics.porosity.neutron_porosity(nphi, vsh, phish)

Estimate the effective porosity from the neutron log (Schön[2]).

Parameters:

• nphi (array_like) – Neutron porosity log.

• vsh (array_like) – Total volume of shale in the rock, chosen the most representative.

• phi_nsh (int, float) – Apparent porosity read in the shales on and under the layer under study and with the same values used in φN.

Returns:

phin – Effective porosity from the neutron log for the aimed interval.

Return type:

array_like

stoneforge.petrophysics.porosity.porosity(method='density', **kwargs)

Compute porosity from well logs.

This is a façade for the methods:

• density: stoneforge.petrophysics.porosity.density_porosity()

• neutron: stoneforge.petrophysics.porosity.neutron_porosity()

• neutron-density: stoneforge.petrophysics.porosity.neutron_density_porosity()

• sonic: stoneforge.petrophysics.porosity.sonic_porosity()

• gaymard: stoneforge.petrophysics.porosity.gaymard_porosity()

• effective: stoneforge.petrophysics.porosity.effective_porosity()

Parameters:

• rhob (array_like) – Bulk density log. Required if method is “denisty”.

• rhom (int, float) – Matrix density. Required if method is “denisty”.

• rhof (int, float) – Density of the fluid saturating the rock (Usually 1.0 for water and 1.1 for saltwater mud). Required if method is “denisty”.

• nphi (array_like) – Neutron log. Required if method is “neutron”.

• vsh (array_like) – Total volume of shale in the rock, chosen the most representative. Required if method is “neutron” or “effective”.

• phi_nsh (int, float) – Apparent porosity read in the shales on and under the layer under study and with the same values used in φN. Required if method is “neutron”.

• dt (array_like) – Sonic log reading (acoustic transit time (μsec/ft)). Required if method is “sonic”.

• dtma (int, float) – Acoustic transit time of the matrix (μsec/ft). Required if method is “sonic”.

• dtf (int, float) – Acoustic transit time of the fluids, usually water (μsec/ft). Required if method is “sonic”.

• phid (array_like) – Density porosity (porosity calculated using density log). Required if method is “neutron-density” or “gaymard.

• phin (int, float) – Neutron porosity (porosity calculated using neutron log). Required if method is “neutron-density” or “gaymard.

• phi (int, float) – Total porisity. Required if method is “effective”.

• method (str, optional) –

  Name of the method to be used. Should be one of

  • ’density’

  • ’neutron’

  • ’neutron-density’

  • ’sonic’

  • ’gaymard’

  • ’effective’

  If not given, default method is ‘density’

Returns:

phi – Porosity log using the defined method.

Return type:

array_like

stoneforge.petrophysics.porosity.sonic_porosity(dt, dtma, dtf)

Estimate the Porosity from sonic using the Wyllie et al.[4] time-average equation.

Parameters:

• dt (array_like) – Sonic log reading (acoustic transit time (μsec/ft))

• dtma (int, float) – Acoustic transit time of the matrix (μsec/ft)

• dtf (int, float) – Acoustic transit time of the fluids, usually water (μsec/ft)

Returns:

phidt – Porosity from sonic.

Return type:

array_like

Shale Volume

stoneforge.petrophysics.shale_volume.gammarayindex(gr, grmin, grmax)

Calculates the gamma ray index Schön[2].

Parameters:

• gr (array_like) – Gamma Ray log.

• grmin (float) – Clean sand GR value.

• grmax (float) – Shale/clay value.

Returns:

igr – The gamma ray index varying between 0.0 (clean sand) and 1.0 (shale).

Return type:

array_like

stoneforge.petrophysics.shale_volume.vshale(method='density', **kwargs)

Compute the shale volume from gamma ray log.

This is a façade for the methods:

• vshale_linear: stoneforge.petrophysics.shale_volume.vshale_linear()

• vshale_larionov: stoneforge.petrophysics.shale_volume.vshale_larionov()

• vshale_larionov_old: stoneforge.petrophysics.shale_volume.vshale_larionov_old()

• vshale_clavier: stoneforge.petrophysics.shale_volume.vshale_clavier()

• vshale_stieber: stoneforge.petrophysics.shale_volume.vshale_stieber()

• vshale_neu_den: stoneforge.petrophysics.shale_volume.vshale_neu_den()

• vshale_nrm: stoneforge.petrophysics.shale_volume.vshale_nrm()

Parameters:

• gr (array_like) – Gamma Ray log.

• grmin (int, float) – Clean sand GR value.

• grmax (int, float) – Shale/clay value.

• method (str, optional) –

  Name of the method to be used. Should be one of the following:

  • ’linear’

  • ’larionov’

  • ’larionov_old’

  • ’clavier’

  • ’stieber’

  • ’neu_den’

  • ’nrm’

  If not given, default method is ‘linear’

Returns:

vshale – Shale Volume for the aimed interval using the defined method.

Return type:

array_like

stoneforge.petrophysics.shale_volume.vshale_clavier(gr, grmin, grmax)

Estimate the shale volume from the Clavier model Clavier et al.[5], Schön[2].

Parameters:

• gr (array_like) – Gamma Ray log.

• grmin (int, float) – Clean sand GR value.

• grmax (int, float) – Shale/clay value.

Returns:

vshale – Shale Volume for the aimed interval using the Clavier method.

Return type:

array_like

stoneforge.petrophysics.shale_volume.vshale_larionov(gr, grmin, grmax)

Estimate the shale volume from the Larionov model for young rocks Larionov[6], Schön[2].

Parameters:

• gr (array_like) – Gamma Ray log.

• grmin (int, float) – Clean sand GR value.

• grmax (int, float) – Shale/clay value.

Returns:

vshale – Shale Volume for the aimed interval using the Larionov method.

Return type:

array_like

stoneforge.petrophysics.shale_volume.vshale_larionov_old(gr, grmin, grmax)

Estimate the shale volume from the Larionov model for old rocks Larionov[6], Schön[2].

Parameters:

• gr (array_like) – Gamma Ray log.

• grmin (int, float) – Clean sand GR value.

• grmax (int, float) – Shale/clay value.

Returns:

vshale – Shale Volume for the aimed interval using the Larionov method.

Return type:

array_like

stoneforge.petrophysics.shale_volume.vshale_linear(gr, grmin, grmax)

Estimate the shale volume from the linear model Schön[2].

Parameters:

• gr (array_like) – Gamma Ray log.

• grmin (int, float) – Clean sand GR value.

• grmax (int, float) – Shale/clay value.

Returns:

vshale – Shale Volume for the aimed interval using the Linear method.

Return type:

array_like

stoneforge.petrophysics.shale_volume.vshale_neu_den(nphi, rhob, clean_n=-0.15, clean_d=2.65, fluid_n=1.0, fluid_d=1.1, clay_n=0.47, clay_d=2.71)

Estimates the shale volume from neutron and density logs method (three points method) Bhuyan and Passey[7].

Parameters:

• nphi (array_like) – Neutron porosity log.

• rhob (array_like) – Bulk density log.

• clean_n (-0.15, float) – Neutron porosity value from clean portion (base quartz).

• clean_d (2.65, float) – Bulk density value from clean portion (base quartz).

• fluid_n (1.00, float) – Neutron porosity value from fluid (base brine).

• fluid_d (1.10, float) – Bulk density value from fluid (base brine).

• clay_n (0.47, float) – Neutron porosity value from clay point (base standard shale).

• clay_d (2.71, float) – Bulk density value from clay point (base standard shale).

Returns:

vshale – Shale volume from neutron and density logs method.

Return type:

array_like

stoneforge.petrophysics.shale_volume.vshale_nrm(phit, phie)

Estimate the shale volume from NMR curves Bhuyan and Passey[7].

Parameters:

• phit (array_like) – Total porosity log from nmr.

• phie (int, float) – Effective porosity log from nmr.

Returns:

vshale – Shale Volume for the aimed interval using NMR curves.

Return type:

array_like

stoneforge.petrophysics.shale_volume.vshale_stieber(gr, grmin, grmax)

Estimate the shale volume from the Stieber model Stieber[8], Schön[2].

Parameters:

• gr (array_like) – Gamma Ray log.

• grmin (int, float) – Clean sand GR value.

• grmax (int, float) – Shale/clay value.

Returns:

vshale – Shale Volume for the aimed interval using the Stieber method.

Return type:

array_like

Water Saturation

stoneforge.petrophysics.water_saturation.archie(rt, phi, rw=0.02, a=1.0, m=2.0, n=2.0)

Estimate the Water Saturation from Archie[9] (standard values from Archie[10], American Association of Petroleum Geologists (AAPG) Wiki[11]).

Parameters:

• rt (array_like) – Formation resistivity.

• phi (array_like) – Porosity.

• rw (float) – Water resistivity.

• a (float) – Tortuosity factor.

• m (float) – Cementation exponent.

• n (float) – Saturation exponent.

Returns:

sw – Water saturation from Archie equation.

Return type:

array_like

stoneforge.petrophysics.water_saturation.fertl(rt, phi, vsh, rw=0.02, a=1.0, m=2.0, alpha=0.3)

Estimate water saturation from Fertl[12] equation (standard values from American Association of Petroleum Geologists (AAPG) Wiki[11]).

Parameters:

• rt (array_like) – True resistivity.

• phi (array_like) – Porosity (must be effective).

• vsh (array_like) – Clay volume log.

• rw (float) – Water resistivity.

• a (int, float) – Tortuosity factor.

• m (int, float) – Cementation exponent.

• alpha (float) – Alpha parameter from Fertl equation.

Returns:

fertl – Water saturation from Fertl equation.

Return type:

array_like

stoneforge.petrophysics.water_saturation.indonesia(rt, phi, vsh, rw=0.02, rsh=4.0, a=1.0, m=2.0, n=2.0)

Estimate water saturation from Poupon and Leveaux[13] equation (standard values from GeoLoil[14], American Association of Petroleum Geologists (AAPG) Wiki[11]).

Parameters:

• phi (array_like) – Porosity.

• vsh (array_like) – Clay volume log.

• rw (float) – Water resistivity.

• rsh (float) – Clay resistivity.

• rt (array_like) – True resistivity.

• a (float) – Tortuosity factor.

• m (float) – Cementation exponent.

• n (float) – Saturation exponent.

Returns:

indonesia – Water saturation from Poupon-Leveaux equation.

Return type:

array_like

stoneforge.petrophysics.water_saturation.simandoux(rt, phi, vsh, rw=0.02, rsh=4.0, a=1.0, m=2.0, n=2.0)

Estimate water saturation from Simandoux[15] equation (standard values from GeoLoil[14], American Association of Petroleum Geologists (AAPG) Wiki[11]).

Parameters:

• phi (array_like) – Porosity.

• vsh (array_like) – Clay volume log.

• rw (float) – Water resistivity.

• rsh (float) – Clay resistivity.

• rt (array_like) – True resistivity.

• a (float) – Tortuosity factor.

• m (float) – Cementation exponent.

• n (float) – Saturation exponent.

Returns:

sw – Water saturation from Simandoux equation.

Return type:

array_like

stoneforge.petrophysics.water_saturation.water_saturation(rw, rt, phi, a, m, method='archie', **kwargs)

Compute water saturation from resistivity log.

This is a façade for the methods:

• archie

• simandoux

• indonesia

• fertl

Parameters:

• rw (int, float) – Water resistivity.

• rt (array_like) – True resistivity.

• phi (array_like) – Porosity (must be effective).

• a (int, float) – Tortuosity factor.

• m (int, float) – Cementation exponent.

• n (int, float) – Saturation exponent. Required if method is “archie”, “simandoux” or “indonesia”.

• vsh (array_like) – Clay volume log. Required if method is “simandoux”, “indonesia” or “fertl”.

• rsh (float) – Clay resistivity. Required if method is “simandoux” or “indonesia”.

• alpha (array_like) – Alpha parameter from Fertl equation. Required if method is “fertl”

• method (str, optional) –

  Name of the method to be used. Should be one of

  • ’archie’

  • ’simandoux’

  • ’indonesia’

  • ’fertl’

  If not given, default method is ‘archie’

Returns:

water_saturation – Water saturation for the aimed interval using the defined method.

Return type:

array_like

References

[1]

Antonio Fernando Menezes Freire. Uma breve introdução à interpretação geológica de perfis geofísicos de poços. 2020. URL: https://www.youtube.com/watch?v=k8yIvVFCguA (visited on 2025-07-27).

[2] (1,2,3,4,5,6,7,8,9,10)

J. Schön. Physical Properties of Rocks: Fundamentals and Principles of Petrophysics. Handbook of geophysical exploration. Geophysical Press, 1998. ISBN 9780080410081. URL: https://shop.elsevier.com/books/physical-properties-of-rocks/schon/978-0-08-100404-3.

[3]

R. Gaymard and A. Poupon. Response of neutron and formation density logs in hydrocarbon bearing formations. The Log Analyst, 09 1968. URL: https://onepetro.org/petrophysics/article/171304/Response-Of-Neutron-And-Formation-Density-Logs-In.

[4]

M. R. J. Wyllie, A. R. Gregory, and L. W. Gardner. Elastic wave velocities in heterogeneous and porous media. GEOPHYSICS, 21(1):41–70, 01 1956. URL: https://library.seg.org/doi/10.1190/1.1438217, doi:10.1190/1.1438217.

[5]

C. Clavier, W. Hoyle, and D. Meunier. Quantitative interpretation of thermal neutron decay time logs: part i. fundamentals and techniques. Journal of Petroleum Technology, 23(06):743–755, 06 1971. URL: http://dx.doi.org/10.2118/2658-A-PA, doi:10.2118/2658-a-pa.

[6] (1,2)

VV Larionov. Borehole radiometry. Nedra, Moscow, 127:813, 1969.

[7] (1,2)

Clay Estimation From Gr And Neutron -Density Porosity Logs, volume All Days of SPWLA Annual Logging Symposium, 06 1994. URL: https://onepetro.org/SPWLAALS/proceedings-pdf/SPWLA-1994/All-SPWLA-1994/SPWLA-1994-DDD/1976313/spwla-1994-ddd.pdf.

[8]

Pulsed Neutron Capture Log Evaluation - Louisiana Gulf Coast, volume Fall Meeting of the Society of Petroleum Engineers of AIME of SPE Annual Technical Conference and Exhibition, 10 1970. URL: https://onepetro.org/SPEATCE/proceedings-pdf/70FM/70FM/SPE-2961-MS/3431325/spe-2961-ms.pdf, doi:10.2118/2961-MS.

[9]

G.E. Archie. The electrical resistivity log as an aid in determining some reservoir characteristics. Transactions of the AIME, 146(01):54–62, 12 1942. URL: https://doi.org/10.2118/942054-G, arXiv:https://onepetro.org/TRANS/article-pdf/146/01/54/2179020/spe-942054-g.pdf, doi:10.2118/942054-G.

[10]

G. E. Archie. Classification of carbonate reservoir rocks and petrophysical considerations. AAPG Bulletin, 36(2):278–298, 02 1952. URL: https://archives.datapages.com/data/bulletns/1949-52/data/pg/0036/0002/0250/0278.htm, doi:10.1306/3D9343F7-16B1-11D7-8645000102C1865D.

[11] (1,2,3,4)

American Association of Petroleum Geologists (AAPG) Wiki. Archie equation. 2014. URL: https://wiki.aapg.org/Archie_equation (visited on 2025-05-29).

[12]

Shaly Sand Analysis In Development Wells, volume All Days of SPWLA Annual Logging Symposium, 06 1975. URL: https://onepetro.org/SPWLAALS/proceedings-pdf/SPWLA-1975/All-SPWLA-1975/SPWLA-1975-A/2064611/spwla-1975-a.pdf.

[13]

Evaluation Of Water Saturation In Shaly Formations, volume All Days of SPWLA Annual Logging Symposium, 05 1971. URL: https://onepetro.org/SPWLAALS/proceedings-pdf/SPWLA-1971/All-SPWLA-1971/SPWLA-1971-O/2064625/spwla-1971-o.pdf.

[14] (1,2)

GeoLoil. Computing water saturation. 2012. URL: https://geoloil.com/computingSW.php (visited on 2025-05-29).

[15]

P. Simandoux. Mesures diélectriques en milieu poreux, application à la mesure des saturations en eau, étude du comportement des massifs argileux. Revue de l’Institut Français du Pétrole, pages 193–215, 1963. Classical reference for the Simandoux water saturation equation.