gem

Models — Mathematical Geoenergy (GEM)

Companion Python models for Mathematical Geoenergy: Discovery, Depletion, and Renewal by Pukite, Challou & Coyne (Wiley/IEEE Press).

Each subdirectory here corresponds to one chapter of the book. It supplies:

A symbolic derivation that reproduces every numbered equation in the chapter using SymPy, with inline assertions verifying each result.
A numerical model that evaluates the equations against real data, generates a labelled composite figure, and saves it as a PNG.
A chapter README that walks through the mathematical argument, lists all key equations in rendered LaTeX, and gives Key Physical Insights.

The unifying methodology across every model is the Principle of Maximum Entropy (MaxEnt): given only a mean (or a small number of moment constraints), MaxEnt uniquely selects an exponential (or compound-exponential) probability distribution for the quantity of interest. Applying MaxEnt once gives an exponential; applying it twice — allowing the local mean to itself be uncertain — yields super-statistics and the Bessel-K or Lomax families. These closed-form results match geophysical and engineering data sets over several orders of magnitude with one or two free parameters.

Current Models

Subdirectory	GEM Chapter	Physical System	Key Distribution
`wind/`	Chapter 11	Wind-speed & wind-energy statistics	Rayleigh / Bessel-K (super-statistics)
`waves/`	Chapter 12.3	Stochastic aquatic wave-height & frequency statistics	Rayleigh CCDF / Pierson-Moskowitz / semi-Markov PSD
`earthquake/`	Chapter 13	Earthquake magnitude dispersion (Gutenberg-Richter)	Exponential / Lomax (super-statistics)
`terrain/`	Chapter 16	Terrain slope distribution (USGS DEM)	Bessel-K₀ (super-statistics)
`electron/`	Chapter 18	Dispersive transport in batteries & PV devices	Laplace dispersive kernel
`flow/`	Chapter 20	Solute / contaminant transport in porous media	Laplace / Cauchy breakthrough curves
`lakes/`	Chapter 15	Lake size distribution	Lomax (Pareto Type II)
`rainfall/`	Chapter 15.3	Dispersive daily rainfall distribution (North Carolina data)	Bessel-K₁ CCDF / Bessel-K₀ PDF (super-statistics)
`thermal_dispersion/`	Chapter 14	Thermal diffusion in disordered geomedia (heat exchangers, ocean heat content)	Laplace dispersive kernel
`EMI/`	Chapter 21	Electromagnetic wave dispersion: 1/f noise & clutter analysis	Lorentzian superposition / Bessel-K₀ (K-distribution)
`corrosion/`	Chapter 19	Corrosion & failure rates: oxide growth, O-U mean reversion, bathtub curve	Laplace dispersive kernel / O-U bounded growth / asymmetric bathtub hazard
`atmos_thermo/`	Chapter 17.1, 17.3	Atmospheric thermodynamics: barometric formula (MaxEnt) & climate sensitivity (Clausius-Clapeyron feedback)	Boltzmann exponential / quadratic GHG feedback
`gompertz/`	Chapter 8.10–8.12	Resource depletion under accelerating extraction: constant, linear-ramp, and Gompertz (exponential-ramp) decline	Exponential decay / Gompertz curve

Common Directory Layout

Every model subdirectory follows the same layout:

models/<topic>/
├── README.md                  # Chapter overview, equations, insights
├── <topic>_symbolic.py        # SymPy derivation — reproduces all numbered equations
├── <topic>_numerical.py       # Numerical evaluation, validation, composite figure
└── <topic>_model_output.png   # Figure produced by <topic>_numerical.py

`<topic>_symbolic.py`

Imports only SymPy.
Defines all symbols and derives each equation step-by-step.
Ends with assert statements (or sympy.simplify equality checks) that verify every result; a passing run prints only ✓ lines.

`<topic>_numerical.py`

Uses NumPy, SciPy, and Matplotlib.
Re-implements the analytical results numerically and plots them against reference data (empirical distributions, published data sets, or synthetic samples).
Saves output to <topic>_model_output.png using MPLBACKEND=Agg so the script runs headlessly in CI.

`README.md`

Section Overview — physical motivation and the MaxEnt argument.
Section Equations — all key equations in LaTeX ($$…$$), grouped by derivation step.
Section Repository Files — table mapping each file to its purpose.
Section Usage — copy-pasteable shell commands.
Section Key Physical Insights — numbered list of takeaways.
Section References — book citation plus primary literature.

Shared Dependencies

All models share the same Python dependencies, listed in requirements.txt:

sympy>=1.12
numpy>=1.24
scipy>=1.11
matplotlib>=3.7

Install with:

pip install -r models/requirements.txt

Running All Models

From the repository root:

pip install -r models/requirements.txt

# Symbolic derivations (verify all equations)
python models/wind/wind_symbolic.py
python models/waves/waves_symbolic.py
python models/earthquake/earthquake_symbolic.py
python models/terrain/terrain_symbolic.py
python models/electron/electron_symbolic.py
python models/flow/flow_symbolic.py
python models/lakes/lake_symbolic.py
python models/rainfall/rainfall_symbolic.py
python models/thermal_dispersion/thermal_dispersion_symbolic.py
python models/EMI/EMI_symbolic.py
python models/corrosion/corrosion_symbolic.py
python models/atmos_thermo/atmos_thermo_symbolic.py
python models/gompertz/gompertz_symbolic.py

# Numerical models (generate output figures)
MPLBACKEND=Agg python models/wind/wind_numerical.py
MPLBACKEND=Agg python models/waves/waves_numerical.py
MPLBACKEND=Agg python models/earthquake/earthquake_numerical.py
MPLBACKEND=Agg python models/terrain/terrain_numerical.py
MPLBACKEND=Agg python models/electron/electron_numerical.py
MPLBACKEND=Agg python models/flow/flow_numerical.py
MPLBACKEND=Agg python models/lakes/lake_numerical.py
MPLBACKEND=Agg python models/rainfall/rainfall_numerical.py
MPLBACKEND=Agg python models/thermal_dispersion/thermal_dispersion_numerical.py
MPLBACKEND=Agg python models/EMI/EMI_numerical.py
MPLBACKEND=Agg python models/corrosion/corrosion_numerical.py
MPLBACKEND=Agg python models/atmos_thermo/atmos_thermo_numerical.py
MPLBACKEND=Agg python models/gompertz/gompertz_numerical.py

Adding a New Model

To contribute a model for a new GEM chapter, follow these steps:

Create the subdirectory
```
mkdir models/<topic>
```
Write <topic>_symbolic.py
- Import only SymPy (from sympy import *).
- Define all symbols with symbols(...).
- Derive each numbered equation and assert correctness.
- Print "✓ Eq. X-Y" after each passing assertion.
Write <topic>_numerical.py
- Import NumPy, SciPy, Matplotlib.
- Implement the analytical results as Python functions.
- Plot predicted vs. empirical (or reference) data in a composite figure with labelled subplots.
- Save with plt.savefig("<topic>_model_output.png", ...).
- Guard the entry point: if __name__ == "__main__": main().

Add the output PNG by running the numerical script once:

MPLBACKEND=Agg python models/<topic>/<topic>_numerical.py

Write README.md using the section structure described above.
Update this file — add a row to the Current Models table.

Common MaxEnt Patterns

The table below summarises the recurring mathematical structures that appear across chapters:

Pattern	Mechanism	Resulting distribution	Appears in
Single MaxEnt prior on rate/energy	Known mean only	Exponential	All models
MaxEnt on $E$; transform $E \propto \nu^2$	Kinetic energy	Rayleigh	wind Ch. 11
MaxEnt on $E$; transform $E \propto H^2$; Newton $H \sim 1/f^2$	Wave energy → frequency	Rayleigh CCDF / Pierson-Moskowitz $f^{-5}$	waves Ch. 12.3
Shifted-exponential spacing; Fourier power spectrum	Ordered vs random wave trains	Semi-Markov harmonic PSD	waves Ch. 12.3
Super-statistics (MaxEnt on mean energy)	Two nested exponentials	Bessel-K₁ CDF / Bessel-K₀ PDF	wind Ch. 11, terrain Ch. 16, rainfall Ch. 15.3
Two MaxEnt exponentials integrated over depth	Rate × depth	Lomax (Pareto-II)	lakes Ch. 15, flow Ch. 20
MaxEnt on diffusion coefficient $D$; Gaussian FPE	Disordered $D$	Laplace dispersive kernel	thermal Ch. 14, electron Ch. 18, flow Ch. 20, corrosion Ch. 19
MaxEnt on velocity; delta-function FPE	Disordered advection	Reciprocal exponential / Cauchy	flow Ch. 20
MaxEnt on decay rate; single exponential survival	Mixed rates	Hyperbolic decline	flow Ch. 20
Superposition of MaxEnt Lorentzians; uniform rate prior	Switching-rate disorder	1/f (Lorentzian) PSD	EMI Ch. 21
Two MaxEnt exponentials (intensity + mean); compound fading	Heterogeneous scatterers	Bessel-K₀ K-distribution	EMI Ch. 21
MaxEnt on rate; delta-FPE with $t^2$ search scaling	GPS search-space disorder	Lomax acquisition time	EMI Ch. 21
Laplace dispersive kernel + fresh-surface exposure	Growth + peeling coupling	Power-law corrosion depth $t^{0.7}$	corrosion Ch. 19
O-U mean reversion; bounded diffusion excursion	Restoring force on oxide layer	Saturating growth $W_\infty(1-e^{-t/\tau_c})$	corrosion Ch. 19
MaxEnt on failure-rate population; exponential mix	Infant-mortality + wear-out	Asymmetric bathtub hazard $h_0 e^{-\delta t} + \mu_f t$	corrosion Ch. 19
MaxEnt on molecular energy in gravity field	Hydrostatic equilibrium	Boltzmann exponential → barometric formula $P_0 e^{-Mgz/RT}$	atmos_thermo Ch. 17.1
Log-sensitivity + Clausius-Clapeyron Boltzmann activation; quadratic self-consistency	GHG-temperature feedback	Quadratic two-root climate equilibrium; $\alpha \approx 15.1$ °C per ln-unit	atmos_thermo Ch. 17.3
Proportional depletion ODE; constant extraction rate	Finite-reserve exponential extraction	Exponential decline $U_0 e^{-kt}$	gompertz Ch. 8.10
Proportional depletion with exponentially-growing extraction rate	Gompertz resource collapse	Gompertz $U_0 \exp(-(kt + ae^{bt}/b))$	gompertz Ch. 8.11

Reference

Pukite, P., Challou, D., & Coyne, C. (2019). Mathematical Geoenergy: Discovery, Depletion, and Renewal. Wiley/IEEE Press. ISBN 978-1-119-43429-0.

Publisher page