Porosity

The library provides a set of conventional porosity estimation techniques derived from density, neutron, and sonic well logs, as well as hybrid formulations designed to mitigate lithology and shale effects. These methods reflect standard petrophysical models and enable users to compute both total and effective porosity under varying geological and logging conditions.

• Density-based porosity calculations rely on the bulk density response of the formation. The Density Porosity model estimates total porosity from the contrast between the measured bulk density (RHOB) and assumed matrix (ρ_ma) and fluid (ρ_f) densities. This formulation is grounded in the volumetric mixing law and is particularly effective in clean formations where matrix properties are reasonably constrained.

• Neutron-derived porosity exploits the sensitivity of neutron tools to hydrogen concentration. The Neutron Porosity estimator corrects the raw neutron response for shale effects by incorporating shale volume (Vsh) and an apparent shale porosity term. This correction is essential because bound water in clays can significantly inflate neutron readings, leading to overestimated porosity if untreated.

• Sonic-based porosity is computed using the Wyllie Time-Average Equation, which models acoustic transit time (Δt) as a linear combination of matrix and fluid contributions. Sonic porosity is often useful in consolidated formations but may require caution in poorly compacted or complex lithologies where the time-average assumption breaks down.

To improve robustness and reduce tool-specific biases, the library includes combined estimators:

• Neutron–Density Porosity – Computes effective porosity from the joint response of density and neutron logs. Depending on configuration, the estimator uses either the arithmetic mean or a root-mean-square formulation, helping stabilize results where individual logs are affected by lithology or fluid variations.

• Gaymard–Poupon Method – A crossplot-inspired correction that integrates neutron and density porosities to better resolve shale-free porosity. This method is widely applied in shaly sand interpretations to compensate for systematic tool deviations.

Effective porosity calculations are also explicitly supported:

• Effective Porosity – Derives shale-corrected porosity from total porosity and shale volume, accounting for the non-reservoir pore space associated with clays. This adjustment is critical for volumetric evaluations and saturation models.

For workflow simplification, the library exposes a façade function that unifies all porosity models under a single interface. This design allows users to select estimation methods based on available logs, formation characteristics, and interpretation strategy while maintaining methodological consistency across analyses.

Porosity

stoneforge.petrophysics.porosity.density_porosity(rhob, rhom=2.65, rhof=1.1)

Estimate the porosity from the bulk density log (Schön[1]). rw: Annotated[float, “Water resistivity”]

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, phi_sh=0.05)

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

Parameters:

• phi (array_like) – Porosity log

• vsh (array_like) – Shale volume

• phi_sh (float) – Apparent porosity in shales

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[2] 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[1]).

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

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

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=55.5, dtf=175)

Estimate the Porosity from sonic using the Wyllie et al.[3] 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

References

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

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.

[2]

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.

[3]

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.