Rock Physics

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

Elastic Constants

stoneforge.rock_physics.elastic_constants.bulk_modulus(rho, vp, vs)

Computes the bulk modulus using density, shear wave velocity and compressional wave velocity (Simm and Bacon[2]).

Parameters:

• rho (array_like) – Density data in g/cm³.

• vp (array_like) – Compressional wave velocity data in km/s.

• vs (array_like) – Shear wave velocity data in km/s.

Returns:

K – Bulk modulus data in Pascal unit (S/I).

Return type:

array_like

stoneforge.rock_physics.elastic_constants.compressional_modulus(rho, vp)

Computes the Compressional modulus using density and compressional wave velocity (Simm and Bacon[2]).

Parameters:

• rho (array_like, float) – Density data in g/cm³.

• vp (array_like, float) – Compressional wave velocity in km/s².

Returns:

M – Compressional modulus data Pascal (Pa).

Return type:

array_like, float

stoneforge.rock_physics.elastic_constants.compressional_wave_velocity(method='rhob_and_g_and_k', **kwargs)

Compute the compressional (P-wave) velocity using different elastic property methods (Simm and Bacon[2]).

Parameters:

• method ({'rhob_and_g_and_k', 'rhob_and_m'}) – Method used to compute compressional wave velocity. - ‘rhob_and_g_and_k’ : Requires bulk modulus (K), shear modulus (G), and density (RHOB). - ‘rhob_and_m’ : Requires compressional modulus (M) and density (RHOB).

• rhob (float or array_like) – Bulk density of the medium [g/cm³ or kg/m³ depending on units consistency].

• g (float or array_like, (optional)) – Shear modulus (G) [same unit system as K]. Required for ‘rhob_and_g_and_k’.

• k (float or array_like, (optional)) – Bulk modulus (K) [Pa or similar]. Required for ‘rhob_and_g_and_k’.

• m (float or array_like, (optional)) – Compressional modulus (M = K + 4G/3) [Pa]. Required for ‘rhob_and_m’.

Returns:

vp – Compressional wave velocity [m/s] or consistent unit.

Return type:

float or array_like

Raises:

TypeError – If required parameters are missing for the selected method.

Examples

>>> compressional_wave_velocity('rhob_and_g_and_k', rhob=2.5, g=30e9, k=45e9)
6000.0

>>> compressional_wave_velocity('rhob_and_m', rhob=2.5, m=75e9)
6000.0

stoneforge.rock_physics.elastic_constants.poisson(method='k_and_g', **kwargs)

Compute Poisson’s ratio (ν) using different pairs of elastic moduli (Simm and Bacon[2]).

Parameters:

• method ({'k_and_g', 'vp_and_vs', 'e_and_k'}) – Method used to compute Poisson’s ratio: - ‘k_and_g’ : Requires bulk modulus (K) and shear modulus (G). - ‘vp_and_vs’ : Requires compressional (P-wave) velocity (VP) and shear (S-wave) velocity (VS). - ‘e_and_k’ : Requires Young’s modulus (E) and bulk modulus (K).

• k (float or array_like, (optional)) – Bulk modulus [Pa or similar]. Required for ‘k_and_g’ and ‘e_and_k’.

• g (float or array_like, (optional)) – Shear modulus [Pa]. Required for ‘k_and_g’.

• e (float or array_like, (optional)) – Young’s modulus [Pa]. Required for ‘e_and_k’.

• vp (float or array_like, (optional)) – Compressional wave velocity [m/s]. Required for ‘vp_and_vs’.

• vs (float or array_like, (optional)) – Shear wave velocity [m/s]. Required for ‘vp_and_vs’.

Returns:

v – Poisson’s ratio (dimensionless).

Return type:

float or array_like

Raises:

TypeError – If required parameters for the selected method are missing.

Examples

>>> poisson('k_and_g', k=36e9, g=45e9)
0.2

>>> poisson('vp_and_vs', vp=6000, vs=3464)
0.25

>>> poisson('e_and_k', e=90e9, k=36e9)
0.2

stoneforge.rock_physics.elastic_constants.shear_modulus(rho, vs)

Computes the shear modulus using density and s wave velocity (Simm and Bacon[2]).

Parameters:

• rho (array_like) – Density data in g/cm³.

• vs (array_like) – Compressional wave velocity data in km/s.

Returns:

U – Shear modulus data in Pascal unit.

Return type:

array_like

stoneforge.rock_physics.elastic_constants.shear_wave_velocity(rho, u)

Computes the shear wave velocity using density and shear modulus (Simm and Bacon[2]).

Parameters:

• rho (array_like, float) – Density data in g/cm³.

• u (array_like, float) – Shear modulus data in Pascal unit.

Returns:

vs – Shear wave velocity data km/s.

Return type:

array_like, float

Fluid Substitution

stoneforge.rock_physics.fluid_substitution.gassmann(phi, ks, method='gassmann_subs', **kwargs)

Compute Gassmann[3] fluid substitution and modulus equations (Mavko et al.[4]).

This function serves as a façade for different Gassmann-related methods:

• Dry-rock bulk modulus estimation (kdry)

• Saturated-rock bulk modulus estimation (ksat)

• Gassmann fluid substitution (gassmann_subs)

Parameters:

• phi (array_like) – Porosity of the rock [fractional, e.g., 0.25 for 25%].

• ks (array_like) – Bulk modulus of the solid grain matrix [GPa or consistent unit].

• method ({'kdry', 'ksat', 'gassmann_subs'}, default='gassmann_subs') – The Gassmann equation variant to apply. - ‘kdry’ : Compute dry rock bulk modulus from known saturated rock. - ‘ksat’ : Compute saturated rock bulk modulus from dry rock. - ‘gassmann_subs’ : Substitute fluid in the saturated rock.

• ksatA (array_like, optional) – Saturated bulk modulus with fluid A [GPa]. Required for ‘kdry’ and ‘gassmann_subs’.

• kfluidA (array_like, optional) – Bulk modulus of fluid A [GPa]. Required for ‘kdry’ and ‘gassmann_subs’.

• kfluidB (array_like, optional) – Bulk modulus of fluid B [GPa]. Required for ‘ksat’ and ‘gassmann_subs’.

• kdry (array_like, optional) – Dry rock bulk modulus [GPa]. Required for ‘ksat’.

Returns:

ksat – Bulk modulus of rock saturated with fluid B [GPa].

Return type:

array_like

Raises:

• TypeError – If required parameters for the selected method are missing.

• ValueError – If an unsupported method is specified.

Examples

>>> gassmann(phi=0.25, ks=36, method="kdry", ksatA=25, kfluidA=2.2)
array([...])

>>> gassmann(phi=0.25, ks=36, method="gassmann_subs", ksatA=25, kfluidA=2.2, kfluidB=1.5)
array([...])

stoneforge.rock_physics.fluid_substitution.gassmann_subs(phi, ks, ksatA, kfluidA, kfluidB)

Fluid substitution using Gassmann[3] equation without calculating dry-rock bulk modulus (Avseth et al.[5]).

Parameters:

• phi (array_like) – Porosity log.

• ks (array_like) – Bulk modulus of solid phase.

• ksatA (array_like) – Bulk modulus of the rock saturated with fluid A.

• kfluidA (array_like) – Bulk modulus of the fluid A.

• kfluidB (array_like) – Bulk modulus of the fluid B.

Returns:

ksat – Bulk modulus of rock saturated with fluid B.

Return type:

array_like

stoneforge.rock_physics.fluid_substitution.kdry(phi, ks, ksatA, kfluidA)

Calculate the dry-rock bulk modulus using Gassmann[3] equation (Dvorkin et al.[6]).

Parameters:

• phi (array_like) – Porosity information.

• ks (array_like) – Bulk modulus of solid phase.

• ksatA (array_like) – Bulk modulus of the rock phase saturated with fluid A.

• kfluidA (array_like) – Bulk modulus of the fluid A.

Returns:

kdry – Dry-rock bulk modulus.

Return type:

array_like

stoneforge.rock_physics.fluid_substitution.ksat(phi, ks, kdry, kfluidB)

Calculate the bulk modulus of the rock saturated with fluid B (Dvorkin et al.[6]).

Parameters:

• phi (array_like) – Porosity log.

• ks (array_like) – Bulk modulus of solid phase.

• kdry (array_like) – Bulk modulus of the dry-rock.

• kfluidB (array_like) – Bulk modulus of the fluid B.

Returns:

ksat – Bulk modulus of the rock saturated with fluid B.

Return type:

array_like

stoneforge.rock_physics.fluid_substitution.mavko(phi, ms, method='mavko_subs', **kwargs)

Compute Mavko et al.[4] fluid substitution and modulus equations.

This is a façade for different Mavko equation implementations:

• Dry-rock compressional modulus (mdry)

• Saturated-rock compressional modulus (msat)

• Mavko fluid substitution (mavko_subs)

Parameters:

• phi (array_like) – Porosity of the rock [fractional, e.g., 0.25 for 25%].

• ms (array_like) – Compressional modulus of the solid phase [GPa].

• method ({'mdry', 'msat', 'mavko_subs'}, default='mavko_subs') – The Mavko equation variant to apply. - ‘mdry’ : Estimate dry rock modulus from saturated rock. - ‘msat’ : Estimate saturated rock modulus from dry rock. - ‘mavko_subs’ : Perform fluid substitution using two fluids.

• msatA (array_like, optional) – Compressional modulus of rock saturated with fluid A [GPa]. Required for ‘mdry’ and ‘mavko_subs’.

• kfluidA (array_like, optional) – Bulk modulus of fluid A [GPa]. Required for ‘mdry’ and ‘mavko_subs’.

• kfluidB (array_like, optional) – Bulk modulus of fluid B [GPa]. Required for ‘msat’ and ‘mavko_subs’.

• mdry (array_like, optional) – Compressional modulus of dry rock [GPa]. Required for ‘msat’.

Returns:

msat – Compressional modulus of rock saturated with fluid B [GPa].

Return type:

array_like

Raises:

• TypeError – If required parameters for the selected method are missing.

• ValueError – If an unsupported method is provided.

Examples

>>> mavko(phi=0.25, ms=39, method="mdry", msatA=32, kfluidA=2.2)
array([...])

>>> mavko(phi=0.25, ms=39, method="mavko_subs", msatA=32, kfluidA=2.2, kfluidB=1.5)
array([...])

stoneforge.rock_physics.fluid_substitution.mavko_subs(phi, ms, msatA, kfluidA, kfluidB)

Fluid substitution using Mavko et al.[4] equation without calculating dry-rock bulk modulus (Dvorkin et al.[6]).

Parameters:

• phi (array_like) – Porosity log.

• ms (array_like) – Compressional modulus of solid phase.

• msatA (array_like) – Compressional modulus of the rock saturated with fluid A.

• kfluidA (array_like) – Bulk modulus of the fluid A.

• kfluidB (array_like) – Bulk modulus of the fluid B.

Returns:

msat – Compressional modulus of rock saturated with fluid B.

Return type:

array_like

stoneforge.rock_physics.fluid_substitution.mdry(phi, ms, msatA, kfluidA)

Calculate the dry-rock compressional modulus using Mavko et al.[4] equation (Dvorkin et al.[6]).

Parameters:

• phi (array_like) – Porosity log.

• ms (array_like) – Compressional modulus of solid phase.

• msatA (array_like) – Compressional modulus of the rock saturated with fluid A.

• kfluidA (array_like) – Bulk modulus of the fluid A.

Returns:

mdry – Dry-rock compressional modulus.

Return type:

array_like

stoneforge.rock_physics.fluid_substitution.msat(phi, ms, mdry, kfluidB)

Calculate the compressional modulus of the rock saturated with fluid B (Dvorkin et al.[6]).

Parameters:

• phi (array_like) – Porosity log.

• ms (array_like) – Compressional modulus of solid phase.

• mdry (array_like) – Compressional modulus of the dry-rock.

• kfluidB (array_like) – Bulk modulus of the fluid B.

Returns:

msat – Compressional modulus of the rock saturated with fluid B.

Return type:

array_like

Gem

stoneforge.rock_physics.gem.constant_cement(k, g, phi, phic, n, kc, gc, phib, deposition_type='grain_surface')

Computes the elastic moduli of the rock using the constant cement model (Dvorkin et al.[6]).

Parameters:

• k (float) – Bulk modulus of the mineral.

• g (float) – Shear modulus of the mineral.

• phi (array_like) – Porosity value or log.

• phic (float) – Critical porosity.

• n (float) – Coordination number.

• kc (float) – Bulk modulus of the cementing mineral.

• gc (float) – Shear modulus of the cementing mineral.

• phib (float) – Porosity where the cement effect starts.

• deposition_type (str) – Cement deposition framework: grain_surface or grain_contact

Return type:

array

Returns:

• kconst (array_like) – Bulk modulus using the constant cement model.

• gconst (array_like) – Shear modulus using the constant cement model.

stoneforge.rock_physics.gem.contact_cement(k, g, phi, phic, n, kc, gc, deposition_type='grain_surface')

Computes the elastic moduli of the rock using the contact cement model (Dvorkin et al.[6]).

Parameters:

• k (float) – Bulk modulus of the mineral.

• g (float) – Shear modulus of the mineral.

• phi (array_like) – Porosity value or log.

• phic (float) – Critical porosity.

• n (float) – Coordination number.

• kc (float) – Bulk modulus of the cementing mineral.

• gc (float) – Shear modulus of the cementing mineral.

• deposition_type (str) – Cement deposition framework: grain_surface or grain_contact

Return type:

array

Returns:

• kcem (array_like) – Bulk modulus using the contact cement model.

• gcem (array_like) – Shear modulus using the contact cement model.

stoneforge.rock_physics.gem.gem(k, g, phi, phic, n, method='soft_sand', **kwargs)

Compute the elastic moduli using granular effective medium (GEM) rock physics models (Dvorkin et al.[6], Dvorkin et al.[7]).

This function wraps several GEM-based models including:

• Soft sand model

• Stiff sand model

• Contact cement model

• Constant cement model

Parameters:

• k (float) – Bulk modulus of the mineral frame [GPa].

• g (float) – Shear modulus of the mineral frame [GPa].

• phi (array_like) – Porosity log or scalar value [fractional].

• phic (float) – Critical porosity [fractional].

• n (float) – Coordination number (average number of grain contacts).

• method ({'soft_sand', 'stiff_sand', 'contact_cement', 'constant_cement'}, default='soft_sand') – The granular effective medium model to apply.

• p (float, (optional)) – Confining pressure [MPa]. Required for ‘soft_sand’ and ‘stiff_sand’.

• kc (float, (optional)) – Bulk modulus of cement [GPa]. Required for ‘contact_cement’ and ‘constant_cement’.

• gc (float, (optional)) – Shear modulus of cement [GPa]. Required for ‘contact_cement’ and ‘constant_cement’.

• phib (float, (optional)) – Porosity at the beginning of cementation [fractional]. Required for ‘constant_cement’.

Return type:

tuple[array, array]

Returns:

• k_model (array_like) – Bulk modulus computed from the chosen model [GPa].

• g_model (array_like) – Shear modulus computed from the chosen model [GPa].

Raises:

• TypeError – If required parameters for the selected model are missing.

• ValueError – If an unsupported method is specified.

Examples

>>> gem(k=36, g=45, phi=0.25, phic=0.4, n=8, method="soft_sand", p=20)
(array([...]), array([...]))

>>> gem(k=36, g=45, phi=0.25, phic=0.4, n=8, method="constant_cement", kc=20, gc=25, phib=0.3)
(array([...]), array([...]))

stoneforge.rock_physics.gem.gem_model(k, g, phic, n, method='soft_sand', **kwargs)

Compute bulk and shear moduli from granular effective medium models for visualization (Dvorkin et al.[6]).

This façade function wraps four common GEM rock-physics models:

• Soft sand

• Stiff sand

• Contact cement

• Constant cement

A porosity array from 0 to critical porosity (phic) is used as input.

Parameters:

• k (float) – Bulk modulus of the mineral phase [GPa].

• g (float) – Shear modulus of the mineral phase [GPa].

• phic (float) – Critical porosity [fractional].

• n (float) – Coordination number (typically 6–10).

• method ({'soft_sand', 'stiff_sand', 'contact_cement', 'constant_cement'}, default='soft_sand') – The GEM model to use.

• p (float, optional) – Confining pressure [MPa]. Required for ‘soft_sand’ and ‘stiff_sand’.

• kc (float, optional) – Bulk modulus of the cement [GPa]. Required for ‘contact_cement’ and ‘constant_cement’.

• gc (float, optional) – Shear modulus of the cement [GPa]. Required for ‘contact_cement’ and ‘constant_cement’.

• phib (float, optional) – Porosity where cementation begins [fractional]. Required for ‘constant_cement’.

Return type:

tuple[array, array]

Returns:

• k_model (array_like) – Bulk modulus curve [GPa].

• g_model (array_like) – Shear modulus curve [GPa].

Raises:

• TypeError – If any required parameter for the selected method is missing.

• ValueError – If the selected method is invalid.

Examples

>>> gem_model(k=36, g=45, phic=0.4, n=8, method="soft_sand", p=25)
(array([...]), array([...]))

>>> gem_model(k=36, g=45, phic=0.4, n=8, method="constant_cement", kc=25, gc=30, phib=0.28)
(array([...]), array([...]))

stoneforge.rock_physics.gem.hertz_mindlin(k, g, n, phic, p)

Computes the elastic moduli of the original room-dry grain pack at critical porosity phic from Hertz-Mindlin (Hertz[8], Mindlin[9]) contact theory (Dvorkin et al.[6]).

Parameters:

• k (float) – Bulk modulus of the mineral.

• g (float) – Shear modulus of the mineral.

• n (float) – Coordination number.

• phic (float) – Critical porosity.

• p (float) – Hydrostatic confining pressure.

Return type:

float

Returns:

• khm (float) – Bulk modulus of the Hertz-Mindlin point.

• ghm (float) – Shear modulus of the Hertz-Mindlin point.

stoneforge.rock_physics.gem.soft_sand(k, g, phi, phic, n, p)

Computes the elastic moduli of the rock using the soft sand model (Dvorkin et al.[6]).

Parameters:

• k (float) – Bulk modulus of the mineral.

• g (float) – Shear modulus of the mineral.

• phi (array_like) – Porosity value or log.

• phic (float) – Critical porosity.

• n (float) – Coordination number.

• p (float) – Hydrostatic confining pressure.

Return type:

array

Returns:

• ksoft (array_like) – Bulk modulus using the soft sand model.

• gsoft (array_like) – Shear modulus using the soft sand model.

stoneforge.rock_physics.gem.stiff_sand(k, g, phi, phic, n, p)

Computes the elastic moduli of the rock using the stiff sand model (Dvorkin et al.[6]).

Parameters:

• k (float) – Bulk modulus of the mineral.

• g (float) – Shear modulus of the mineral.

• phi (array_like) – Porosity value or log.

• phic (float) – Critical porosity.

• n (float) – Coordination number.

• p (float) – Hydrostatic confining pressure.

Return type:

array

Returns:

• kstiff (array_like) – Bulk modulus using the stiff sand model.

• gstiff (array_like) – Shear modulus using the stiff sand model.

Rock Physics Bounds

stoneforge.rock_physics.rock_physics_bounds.hill(f, m)

Calculate elastic modulus of the effective mineral using the Hill[10] average (Dvorkin et al.[7].

Parameters:

• f (array_like) – Fractions (proportions) of each mineral.

• m (array_like) – Elastic modulus of each mineral.

Returns:

v – Hill average.

Return type:

array_like

stoneforge.rock_physics.rock_physics_bounds.reuss(f, m)

Calculate elastic modulus of the effective mineral using the Reuss[11] bound (Dvorkin et al.[7]).

Parameters:

• f (array_like) – Fractions (proportions) of each mineral.

• m (array_like) – Elastic modulus of each mineral.

Returns:

r – Reuss bound.

Return type:

array_like

stoneforge.rock_physics.rock_physics_bounds.voigt(f, m)

Calculate elastic modulus of the effective mineral using the Voigt[12] bound (Dvorkin et al.[7]).

Parameters:

• f (array_like) – Fractions (proportions) of each mineral.

• m (array_like) – Elastic modulus of each mineral.

Returns:

v – Voigt bound.

Return type:

array_like

References

[1]

Wagner Moreira Lupinacci. Modelagem sísmica de propriedades de rochas. 2020. URL: https://www.youtube.com/playlist?list=PL-QDjrxb17QNBRUUR3_xU1XI28Ts8QGlK (visited on 2025-07-27).

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

Rob Simm and Mike Bacon. Seismic Amplitude: An Interpreter’s Handbook. Cambridge University Press, 04 2014. ISBN 9781107011502. URL: https://www.cambridge.org/core/books/seismic-amplitude/D3C75760BEB24839DF42216E8B268A66, doi:10.1017/cbo9780511984501.

[3] (1,2,3)

Fritz Gassmann. Elastic waves through a packing of spheres. Geophysics, 16(4):673–685, 1951. URL: https://library.seg.org/doi/abs/10.1190/1.1437718, doi:10.1190/1.1437718.

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

Gary Mavko, Tapan Mukerji, and Jack Dvorkin. The Rock Physics Handbook: Tools for Seismic Analysis of Porous Media. Cambridge University Press, 04 2009. ISBN 9780511626753. URL: https://www.cambridge.org/core/books/rock-physics-handbook/A53F53ADFDD5D72EF01A9E4C6E9454A7, doi:10.1017/cbo9780511626753.

[5]

Per Avseth, Tapan Mukerji, and Gary Mavko. Quantitative Seismic Interpretation: Applying Rock Physics Tools to Reduce Interpretation Risk. Cambridge University Press, 02 2005. ISBN 9780521151351. URL: https://www.cambridge.org/core/books/quantitative-seismic-interpretation/EB6A36B78CCF07187723F6F5364EDCF8, doi:10.1017/cbo9780511600074.

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

Jack Dvorkin, Mario A. Gutierrez, and Dario Grana. Seismic Reflections of Rock Properties. Cambridge University Press, 03 2014. ISBN 9780511843655. URL: https://www.cambridge.org/core/books/seismic-reflections-of-rock-properties/79680145E8B02CF09F1514A15121AFF9, doi:10.1017/cbo9780511843655.

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

Jack Dvorkin, Gary Mavko, and Amos Nur. The effect of cementation on the elastic properties of granular material. Mechanics of Materials, 12(3):207–217, 1991. URL: https://www.sciencedirect.com/science/article/pii/016766369190018U, doi:https://doi.org/10.1016/0167-6636(91)90018-U.

[8]

Heinrich Hertz. Ueber die berührung fester elastischer körper. crll, 1882(92):156–171, 1882. URL: https://home.uni-leipzig.de/pwm/web/download/Hertz1881.pdf, doi:10.1515/crll.1882.92.156.

[9]

R. D. Mindlin. Compliance of elastic bodies in contact. Journal of Applied Mechanics, 16(3):259–268, 04 1949. URL: https://asmedigitalcollection.asme.org/appliedmechanics/article/16/3/259/1106367/Compliance-of-Elastic-Bodies-in-Contact, doi:10.1115/1.4009973.

[10]

R. Hill. The elastic behaviour of a crystalline aggregate. Proceedings of the Physical Society. Section A, 65(5):349, 1952. URL: https://iopscience.iop.org/article/10.1088/0370-1298/65/5/307.

[11]

A. Reuss. Berechnung der fließgrenze von mischkristallen auf grund der plastizitätsbedingung für einkristalle. ZAMM-Journal of Applied Mathematics and Mechanics/Zeitschrift für Angewandte Mathematik und Mechanik, 9(1):49–58, 1929. URL: https://onlinelibrary.wiley.com/doi/10.1002/zamm.19290090104.

[12]

W. Voigt. Lehrbuch der Kristallphysik. Vieweg+Teubner Verlag, 1966. ISBN 9783663158844. URL: https://link.springer.com/book/10.1007/978-3-663-15884-4, doi:10.1007/978-3-663-15884-4.