earthsciencekit.plate_tectonics

Domain hub · History · Examples · API reference

Inspectable plate tectonics models; SI units unless stated otherwise.

earthsciencekit.plate_tectonics.airy_root(elevation, crust_density, mantle_density)

Airy crustal compensation.

Crustal buoyancy provides a baseline for mountain-root support.

Parameters:

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

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

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

Returns:

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

Return type:

numpy scalar or ndarray

Notes

Local compensation without plate flexure; mantle must be denser than crust. Equation: elevation * crust_density / (mantle_density - crust_density). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.plate_tectonics.angular_speed(rotation_angle, time)

Euler-pole angular speed.

Rigid plate motion is rotation about an Euler pole.

Parameters:

• rotation_angle (float or array_like) – rad; constraint: real.

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

Returns:

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

Return type:

numpy scalar or ndarray

Notes

Constant angular rate; angular input is radians and output radians per second. Equation: rotation_angle / time. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.plate_tectonics.compose_euler_vectors(omega_ab, omega_bc)

Composition of relative Euler vectors around a plate circuit.

Angular velocities of rigid plates add, so two relative motions predict the third.

Parameters:

• omega_ab (array_like, shape (..., 3)) – rad/s; constraint: real. Earth-fixed Cartesian Euler vector of plate A relative to plate B.

• omega_bc (array_like, shape (..., 3)) – rad/s; constraint: real. Euler vector of plate B relative to plate C.

Returns:

Model value [rad/s]: the Euler vector of plate A relative to plate C. Leading axes broadcast.

Return type:

ndarray, shape (…, 3)

Notes

Instantaneous (infinitesimal) rotations only; finite rotations do not commute and do not add. Closure of the circuit A-B-C means omega_ab + omega_bc + omega_ca = 0. Equation: omega_ab + omega_bc. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.plate_tectonics.convergence_rate(relative_speed, obliquity)

Signed plate-boundary convergence.

Resolving relative motion normal to a boundary separates convergence and shear.

Parameters:

• relative_speed (float or array_like) – m/s; constraint: nonnegative.

• obliquity (float or array_like) – rad; constraint: width.

Returns:

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

Return type:

numpy scalar or ndarray

Notes

Positive normal component denotes convergence; negative denotes divergence. Equation: relative_speed * np.cos(obliquity). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.plate_tectonics.diffuse_temperature(initial, time, diffusivity, spacing)

Evolve a periodic one-dimensional conductive temperature grid.

Parameters:

• initial (array_like, shape (m,), m >= 3) – Positive temperatures [K] on an equally spaced periodic grid.

• time (array_like) – Strictly increasing nonnegative output times [s]. Initial state belongs to the first supplied time; values need not start at zero.

• diffusivity (float) – Positive scalar thermal diffusivity [m^2/s].

• spacing (float) – Positive scalar grid spacing [m].

Returns:

Temperature at each grid point [K]. Columns are labeled cell_0, … .

Return type:

TimeSeries

Notes

The centered discrete Laplacian is diagonalized with a real FFT. Time evolution of that discrete system is exact to floating-point accuracy. Periodicity conserves mean temperature. Spatial discretization error remains; this is not the fixed-surface half-space cooling boundary condition.

earthsciencekit.plate_tectonics.euler_velocity_x(omega_y, omega_z, position_y, position_z)

Euler rotation east-fixed x velocity.

The cross product of rotation and position gives Cartesian plate velocity.

Parameters:

• omega_y (float or array_like) – rad/s; constraint: real.

• omega_z (float or array_like) – rad/s; constraint: real.

• position_y (float or array_like) – m; constraint: real.

• position_z (float or array_like) – m; constraint: real.

Returns:

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

Return type:

numpy scalar or ndarray

Notes

Earth-fixed Cartesian axes; x is not the local east component. Equation: omega_y * position_z - omega_z * position_y. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.plate_tectonics.euler_velocity_y(omega_z, omega_x, position_z, position_x)

Euler rotation y velocity.

A rigid plate velocity field is tangent to its spherical path.

Parameters:

• omega_z (float or array_like) – rad/s; constraint: real.

• omega_x (float or array_like) – rad/s; constraint: real.

• position_z (float or array_like) – m; constraint: real.

• position_x (float or array_like) – m; constraint: real.

Returns:

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

Return type:

numpy scalar or ndarray

Notes

Same Earth-fixed Cartesian convention as euler_velocity_x. Equation: omega_z * position_x - omega_x * position_z. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.plate_tectonics.euler_velocity_z(omega_x, omega_y, position_x, position_y)

Euler rotation polar velocity.

The polar velocity component completes the Euler-vector cross product.

Parameters:

• omega_x (float or array_like) – rad/s; constraint: real.

• omega_y (float or array_like) – rad/s; constraint: real.

• position_x (float or array_like) – m; constraint: real.

• position_y (float or array_like) – m; constraint: real.

Returns:

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

Return type:

numpy scalar or ndarray

Notes

Earth-fixed components, not local vertical motion or deformation. Equation: omega_x * position_y - omega_y * position_x. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.plate_tectonics.fault_slip_rate(relative_speed, obliquity)

Tangential boundary slip rate.

The tangential motion component connects oblique convergence to strike slip.

Parameters:

• relative_speed (float or array_like) – m/s; constraint: nonnegative.

• obliquity (float or array_like) – rad; constraint: width.

Returns:

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

Return type:

numpy scalar or ndarray

Notes

Supplied obliquity is oriented from the positive convergence normal. Equation: relative_speed * np.sin(obliquity). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.plate_tectonics.flexural_deflection(distance, line_load, rigidity, density_contrast, gravity)

Elastic plate deflection under a line load.

A load bends the lithosphere into a moat flanked by a peripheral bulge.

Parameters:

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

• line_load (float or array_like) – N/m; constraint: nonnegative.

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

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

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

Returns:

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

Return type:

numpy scalar or ndarray

Notes

Unbroken infinite thin elastic plate, deflection positive downward; density contrast is mantle minus infill. Equation: line_load * alpha**3 / (8 * rigidity) * np.exp(-x) * (np.cos(x) + np.sin(x)) with x = abs(distance) / alpha and alpha = (4 * rigidity / (density_contrast * gravity))**0.25. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.plate_tectonics.flexural_parameter(rigidity, density_contrast, gravity)

Lithosphere flexural length.

Bending and buoyancy jointly set the scale of load compensation.

Parameters:

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

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

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

Returns:

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

Return type:

numpy scalar or ndarray

Notes

Infinite beam-like plate convention alpha to the fourth equals 4D over density contrast times g. Equation: (4 * rigidity / (density_contrast * gravity))**0.25. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.plate_tectonics.flexural_rigidity(young_modulus, elastic_thickness, poisson_ratio)

Elastic lithosphere rigidity.

Elastic thickness turns lithospheric strength into a bending resistance.

Parameters:

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

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

• poisson_ratio (float or array_like) – 1; constraint: poisson.

Returns:

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

Return type:

numpy scalar or ndarray

Notes

Thin isotropic elastic plate with stable Poisson ratio, not a yielding viscoelastic lithosphere. Equation: young_modulus * elastic_thickness**3 / (12 * (1 - poisson_ratio**2)). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.plate_tectonics.full_spreading_rate(half_spreading_rate)

Symmetric full spreading rate.

Opposite plate velocities combine into ridge opening speed.

Parameters:

half_spreading_rate (float or array_like) – m/s; constraint: nonnegative.

Returns:

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

Return type:

numpy scalar or ndarray

Notes

Symmetric spreading; asymmetric velocities require their own relative-vector calculation. Equation: 2 * half_spreading_rate. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.plate_tectonics.halfspace_heat_flux(age, diffusivity, conductivity, surface_temperature, mantle_temperature)

Cooling-plate surface heat flux.

Surface heat flux decreases as an oceanic plate cools.

Parameters:

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

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

• conductivity (float or array_like) – W/(m K); constraint: positive.

• surface_temperature (float or array_like) – K; constraint: positive.

• mantle_temperature (float or array_like) – K; constraint: positive.

Returns:

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

Return type:

numpy scalar or ndarray

Notes

Positive upward flux; semi-infinite conductive model excludes the zero-age singularity. Equation: conductivity * (mantle_temperature - surface_temperature) / np.sqrt(np.pi * diffusivity * age). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.plate_tectonics.halfspace_temperature(depth, age, diffusivity, surface_temperature, mantle_temperature)

Cooling oceanic lithosphere.

Oceanic plates cool as their age and distance from a ridge increase.

Parameters:

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

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

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

• surface_temperature (float or array_like) – K; constraint: positive.

• mantle_temperature (float or array_like) – K; constraint: positive.

Returns:

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

Return type:

numpy scalar or ndarray

Notes

Semi-infinite conduction with fixed surface temperature; no hydrothermal or advective heat transfer. Equation: surface_temperature + (mantle_temperature - surface_temperature) * erf(depth / (2 * np.sqrt(diffusivity * age))). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.plate_tectonics.hotspot_age(track_length, angular_speed, radius, pole_distance)

Age progression along a hotspot track.

A plate moving over a fixed plume leaves volcanoes that age with distance along a small circle.

Parameters:

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

• angular_speed (float or array_like) – rad/s; constraint: positive.

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

• pole_distance (float or array_like) – rad; constraint: open interval (0, pi).

Returns:

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

Return type:

numpy scalar or ndarray

Notes

Fixed hotspot and constant Euler rotation of the plate over it; track length is measured along the small circle. Equation: track_length / (angular_speed * radius * np.sin(pole_distance)). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.plate_tectonics.mantle_rayleigh_number(thermal_expansivity, density, gravity, temperature_difference, thickness, diffusivity, viscosity)

Rayleigh number of a convecting mantle layer.

Buoyancy against viscous and thermal diffusion decides whether the mantle convects.

Parameters:

• thermal_expansivity (float or array_like) – 1/K; constraint: positive.

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

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

• temperature_difference (float or array_like) – K; constraint: nonnegative.

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

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

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

Returns:

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

Return type:

numpy scalar or ndarray

Notes

Layer heated from below with uniform properties; convection starts above about 657.5 (free slip) or 1708 (rigid walls). Equation: thermal_expansivity * density * gravity * temperature_difference * thickness**3 / (diffusivity * viscosity). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.plate_tectonics.ocean_depth(age, ridge_depth, mantle_density, water_density, thermal_expansivity, diffusivity, surface_temperature, mantle_temperature)

Ocean depth of a cooling half-space.

Thermal contraction of the cooling plate makes the sea floor deepen with the square root of its age.

Parameters:

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

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

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

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

• thermal_expansivity (float or array_like) – 1/K; constraint: positive.

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

• surface_temperature (float or array_like) – K; constraint: positive.

• mantle_temperature (float or array_like) – K; constraint: positive.

Returns:

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

Return type:

numpy scalar or ndarray

Notes

Isostatic half-space cooling, depth positive downward; it overestimates depth on sea floor older than about 70 million years. Equation: ridge_depth + 2 * mantle_density * thermal_expansivity * (mantle_temperature - surface_temperature) / (mantle_density - water_density) * np.sqrt(diffusivity * age / np.pi). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.plate_tectonics.plate_displacement(speed, time)

Plate kinematic displacement.

Velocity connects short instrumental records with geological displacement.

Parameters:

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

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

Returns:

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

Return type:

numpy scalar or ndarray

Notes

Constant signed speed along a local coordinate; not a finite Euler rotation. Equation: speed * time. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.plate_tectonics.plate_speed(angular_speed, radius, angular_distance)

Rigid plate speed about an Euler pole.

Distance from the rotation axis controls surface plate speed.

Parameters:

• angular_speed (float or array_like) – rad/s; constraint: nonnegative.

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

• angular_distance (float or array_like) – rad; constraint: width.

Returns:

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

Return type:

numpy scalar or ndarray

Notes

Spherical rigid plate, magnitude only; angular distance must be at most pi. Equation: angular_speed * radius * np.sin(angular_distance). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.plate_tectonics.slab_pull_force(density_excess, slab_volume, gravity)

Slab negative-buoyancy force.

A cold slab can drive motion through its excess weight.

Parameters:

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

• slab_volume (float or array_like) – m^3; constraint: nonnegative.

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

Returns:

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

Return type:

numpy scalar or ndarray

Notes

Simple buoyancy force magnitude; drag, phase changes and mantle flow are excluded. Equation: density_excess * slab_volume * gravity. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.plate_tectonics.spreading_age(distance, half_spreading_rate)

Magnetic-stripe spreading clock.

Symmetric ocean-floor ages link ridge spreading to plate creation.

Parameters:

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

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

Returns:

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

Return type:

numpy scalar or ndarray

Notes

Distance on one side and half-spreading rate; changes in rate are omitted. Equation: distance / half_spreading_rate. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.plate_tectonics.subduction_travel_time(vertical_depth, slab_speed, dip)

Slab path travel time.

Slab dip changes the path length required to reach a specified depth.

Parameters:

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

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

• dip (float or array_like) – rad; constraint: inclination.

Returns:

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

Return type:

numpy scalar or ndarray

Notes

Straight slab at constant speed; zero dip cannot reach depth and is rejected. Equation: vertical_depth / (slab_speed * np.sin(dip)). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.