earthsciencekit.seismology

Domain hub · History · Examples · API reference

Inspectable seismology models; SI units unless stated otherwise.

earthsciencekit.seismology.attenuated_amplitude(amplitude, frequency, time, quality_factor)

Constant-Q wave attenuation.

Finite quality factor models intrinsic amplitude decay during propagation.

Parameters:

• amplitude (float or array_like) – arbitrary amplitude; constraint: real.

• frequency (float or array_like) – Hz; constraint: nonnegative.

• time (float or array_like) – s; constraint: nonnegative.

• quality_factor (float or array_like) – 1; constraint: positive.

Returns:

Model value [m/s]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Constant-Q narrowband attenuation; geometric spreading is separate. Equation: amplitude * np.exp(-np.pi * frequency * time / quality_factor). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.seismology.critical_angle(speed1, speed2)

Snell refraction critical angle.

Snell refraction explains head waves above a faster layer.

Parameters:

• speed1 (float or array_like) – m/s; constraint: positive.

• speed2 (float or array_like) – m/s; constraint: positive.

Returns:

Model value [m/s]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Incidence from the slower medium; second speed must exceed first. Equation: np.arcsin(speed1 / speed2). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.seismology.crossover_distance(thickness, speed1, speed2)

Head-wave crossover distance.

The range at which the refracted wave arrives first measures the depth of the layer.

Parameters:

• thickness (float or array_like) – m; constraint: positive.

• speed1 (float or array_like) – m/s; constraint: positive.

• speed2 (float or array_like) – m/s; constraint: positive.

Returns:

Model value [m]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Flat layer of speed1 over a faster half-space of speed2; direct and head-wave times are equal there. Equation: 2 * thickness * np.sqrt((speed2 + speed1) / (speed2 - speed1)). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.seismology.gutenberg_richter(a, b, magnitude)

Earthquake frequency-size relation.

A logarithmic frequency-size law summarizes an earthquake catalogue.

Parameters:

• a (float or array_like) – 1; constraint: real.

• b (float or array_like) – 1; constraint: positive.

• magnitude (float or array_like) – 1; constraint: real.

Returns:

Model value [m/s]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Expected cumulative count for the fitted catalogue interval; completeness matters. Equation: 10 ** (a - b * magnitude). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.seismology.head_wave_travel_time(distance, thickness, speed1, speed2)

Head-wave travel time below a single layer.

A wave critically refracted along a faster layer overtakes the direct wave at long range.

Parameters:

• distance (float or array_like) – m; constraint: nonnegative, at least the critical distance.

• thickness (float or array_like) – m; constraint: positive.

• speed1 (float or array_like) – m/s; constraint: positive.

• speed2 (float or array_like) – m/s; constraint: positive.

Returns:

Model value [s]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Flat layer of speed1 over a faster half-space of speed2, surface source and receiver. The head wave exists only beyond the critical distance 2 * thickness * tan(critical_angle). Equation: distance / speed2 + 2 * thickness * np.sqrt(speed2**2 - speed1**2) / (speed1 * speed2). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.seismology.local_magnitude(amplitude, distance)

Richter local magnitude.

A logarithm of recorded amplitude, corrected for distance, ranks earthquakes by size.

Parameters:

• amplitude (float or array_like) – m; constraint: positive. Peak Wood-Anderson displacement amplitude.

• distance (float or array_like) – m; constraint: positive. Hypocentral distance.

Returns:

Model value [1]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Richter’s anchor (1 mm at 100 km is magnitude 3) with the Hutton and Boore (1987) southern California distance correction, fitted from about 10 to 700 km. Equation: np.log10(amplitude / 1e-3) + 1.11 * np.log10(distance / 1e5) + 1.89e-6 * (distance - 1e5) + 3. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.seismology.love_wave_angular_frequency(phase_speed, thickness, layer_s_speed, halfspace_s_speed, layer_rigidity, halfspace_rigidity)

Fundamental Love-wave dispersion in a layer over a half-space.

Shear waves trapped in a slow surface layer travel at a speed that depends on their period.

Parameters:

• phase_speed (float or array_like) – m/s; constraint: strictly between the layer and half-space shear speeds.

• thickness (float or array_like) – m; constraint: positive.

• layer_s_speed (float or array_like) – m/s; constraint: positive.

• halfspace_s_speed (float or array_like) – m/s; constraint: positive.

• layer_rigidity (float or array_like) – Pa; constraint: positive.

• halfspace_rigidity (float or array_like) – Pa; constraint: positive.

Returns:

Model value [rad/s]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Fundamental mode of a uniform elastic layer over a faster uniform half-space. Solves tan(k * thickness * s1) = halfspace_rigidity * s2 / (layer_rigidity * s1) for the wavenumber k at the given phase speed, with s1 = np.sqrt(phase_speed**2 / layer_s_speed**2 - 1) and s2 = np.sqrt(1 - phase_speed**2 / halfspace_s_speed**2). Equation: phase_speed * np.arctan(halfspace_rigidity * s2 / (layer_rigidity * s1)) / (thickness * s1). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.seismology.moment_from_magnitude(magnitude)

Inverse moment magnitude.

Inverting magnitude enables comparisons on a physical moment scale.

Parameters:

magnitude (float or array_like) – 1; constraint: real.

Returns:

Model value [m/s]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Same SI convention as moment_magnitude; very large inputs can overflow. Equation: 10 ** (1.5 * magnitude + 9.1). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.seismology.moment_magnitude(moment)

Moment magnitude in SI.

Moment magnitude relates logarithmic event size to scalar moment.

Parameters:

moment (float or array_like) – N m; constraint: positive.

Returns:

Model value [m/s]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Uses the 9.1 intercept with moment in N m, not dyne cm. Equation: (2 / 3) * (np.log10(moment) - 9.1). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.seismology.omori_rate(productivity, offset, exponent, time)

Modified Omori aftershock rate.

Aftershock rates often decay with time after a main shock.

Parameters:

• productivity (float or array_like) – count s^(p-1); constraint: nonnegative.

• offset (float or array_like) – s; constraint: positive.

• exponent (float or array_like) – 1; constraint: positive.

• time (float or array_like) – s; constraint: nonnegative.

Returns:

Model value [m/s]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Empirical fitted rate; no earthquake timing or location prediction. Equation: productivity / (offset + time)**exponent. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.seismology.p_wave_speed(bulk_modulus, shear_modulus, density)

Compressional-wave elasticity.

Elastic moduli and density determine compressional wave speed.

Parameters:

• bulk_modulus (float or array_like) – Pa; constraint: positive.

• shear_modulus (float or array_like) – Pa; constraint: nonnegative.

• density (float or array_like) – kg/m^3; constraint: positive.

Returns:

Model value [m/s]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Homogeneous isotropic small-strain medium; shear modulus may vanish in a fluid. Equation: np.sqrt((bulk_modulus + 4 * shear_modulus / 3) / density). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.seismology.poisson_ratio(p_speed, s_speed)

Elastic velocity ratio.

Wave-speed ratios constrain isotropic elastic response.

Parameters:

• p_speed (float or array_like) – m/s; constraint: positive.

• s_speed (float or array_like) – m/s; constraint: positive.

Returns:

Model value [m/s]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Requires positive bulk modulus: vp squared must exceed 4 vs squared over 3. Equation: (p_speed**2 - 2 * s_speed**2) / (2 * (p_speed**2 - s_speed**2)). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.seismology.ray_parameter(radius, speed, incidence_angle)

Ray parameter in a spherically layered Earth.

Snell’s law on a sphere keeps one quantity fixed along each ray, which fixes where it emerges.

Parameters:

• radius (float or array_like) – m; constraint: positive.

• speed (float or array_like) – m/s; constraint: positive.

• incidence_angle (float or array_like) – rad; constraint: between 0 and pi/2, measured from the radial direction.

Returns:

Model value [s/rad]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Spherically symmetric isotropic Earth; the value is the same at every point of one ray. Equation: radius * np.sin(incidence_angle) / speed. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.seismology.rayleigh_wave_speed(p_speed, s_speed)

Rayleigh surface-wave speed.

A free surface guides a slower wave that combines compression and shear.

Parameters:

• p_speed (float or array_like) – m/s; constraint: positive.

• s_speed (float or array_like) – m/s; constraint: positive.

Returns:

Model value [m/s]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Homogeneous isotropic half-space with a traction-free surface; nondispersive. Requires positive bulk modulus: vp squared must exceed 4 vs squared over 3. Equation: s_speed * np.sqrt(xi), where xi is the root in (0, 1) of xi**3 - 8 * xi**2 + (24 - 16 * gamma) * xi - 16 * (1 - gamma) = 0 and gamma = (s_speed / p_speed)**2, found by bisection to machine precision. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.seismology.reflection_coefficient(impedance1, impedance2)

Normal-incidence pressure reflection.

An interface divides incident energy into reflected and transmitted waves.

Parameters:

• impedance1 (float or array_like) – kg/(m^2 s); constraint: positive.

• impedance2 (float or array_like) – kg/(m^2 s); constraint: positive.

Returns:

Model value [m/s]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Pressure amplitude convention at normal incidence; coefficient can be negative. Equation: (impedance2 - impedance1) / (impedance2 + impedance1). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.seismology.ricker_wavelet(time, frequency)

Ricker seismic source pulse.

A compact pulse makes propagation and filtering examples inspectable.

Parameters:

• time (float or array_like) – s; constraint: real.

• frequency (float or array_like) – Hz; constraint: positive.

Returns:

Model value [m/s]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Unit peak at zero time; frequency is the peak-spectrum convention. Equation: (1 - 2 * (np.pi * frequency * time)**2) * np.exp(-(np.pi * frequency * time)**2). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.seismology.s_wave_speed(shear_modulus, density)

Shear-wave elasticity.

Shear waves reveal rigidity and disappear in an ideal fluid.

Parameters:

• shear_modulus (float or array_like) – Pa; constraint: nonnegative.

• density (float or array_like) – kg/m^3; constraint: positive.

Returns:

Model value [m/s]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Homogeneous isotropic medium; zero shear modulus returns zero speed. Equation: np.sqrt(shear_modulus / density). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.seismology.seismic_impedance(density, speed)

Acoustic impedance.

Impedance contrasts control normal-incidence reflection.

Parameters:

• density (float or array_like) – kg/m^3; constraint: positive.

• speed (float or array_like) – m/s; constraint: positive.

Returns:

Model value [m/s]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Scalar acoustic impedance; elastic mode conversion is excluded. Equation: density * speed. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.seismology.seismic_moment(rigidity, area, slip)

Fault seismic moment.

Moment connects an earthquake to fault area and displacement.

Parameters:

• rigidity (float or array_like) – Pa; constraint: positive.

• area (float or array_like) – m^2; constraint: positive.

• slip (float or array_like) – m; constraint: nonnegative.

Returns:

Model value [m/s]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Scalar mean-slip estimate; no spatial rupture distribution. Equation: rigidity * area * slip. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.seismology.simulate_oscillator(frequency, quality_factor, time, *, displacement=1.0, velocity=0.0)

Integrate an unforced damped seismic oscillator.

Parameters:

• frequency (float) – Positive scalar undamped natural frequency [Hz].

• quality_factor (float) – Positive scalar oscillator Q; damping ratio is 1/(2Q).

• time (array_like) – Nonnegative strictly increasing sampled times [s].

• displacement (float) – Finite scalar initial displacement [m] and velocity [m/s].

• velocity (float) – Finite scalar initial displacement [m] and velocity [m/s].

Returns:

Displacement [m] and velocity [m/s].

Return type:

TimeSeries

Notes

Solves x’’ + omega/Q x’ + omega^2 x = 0. This single oscillator can illustrate a seismometer response; it is not an earthquake rupture model.

earthsciencekit.seismology.transmission_coefficient(impedance1, impedance2)

Normal-incidence pressure transmission.

Pressure transmission differs from transmitted energy fraction.

Parameters:

• impedance1 (float or array_like) – kg/(m^2 s); constraint: positive.

• impedance2 (float or array_like) – kg/(m^2 s); constraint: positive.

Returns:

Model value [m/s]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Normal-incidence acoustic pressure amplitudes, not displacement amplitudes. Equation: 2 * impedance2 / (impedance2 + impedance1). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.seismology.travel_time(distance, speed)

Homogeneous travel time.

Arrival times connect source distance and propagation speed.

Parameters:

• distance (float or array_like) – m; constraint: nonnegative.

• speed (float or array_like) – m/s; constraint: positive.

Returns:

Model value [m/s]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Straight path in a homogeneous medium; not a ray tracer. Equation: distance / speed. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.seismology.vertical_travel_time(depth, speed)

Vertical travel time through a tabulated speed profile.

Integrating slowness through a reference Earth model predicts arrival times.

Parameters:

• depth (array_like, shape (n,), n >= 2) – m; constraint: nonnegative and nondecreasing. A repeated depth marks a discontinuity.

• speed (array_like, shape (n,)) – m/s; constraint: positive.

Returns:

Model value [s]: one-way vertical time from the first depth to each depth.

Return type:

ndarray, shape (n,)

Notes

Speed varies linearly in depth between tabulated points; the integral of each segment is exact. Equation: cumsum(dz * np.log(v2 / v1) / (v2 - v1)), which is dz / v1 where v2 == v1. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.