Ionosphere geodesic FDTD

ionosphere-fdtd is a NumPy and PyTorch implementation of a three-dimensional geodesic finite-difference time-domain model for the Earth–ionosphere waveguide. It combines an icosahedral primal/dual surface mesh with staggered radial Yee planes, conductive materials, localized current sources, receiver sampling, and two- and three-dimensional visualization.

Highlights

• NumPy CPU and PyTorch CPU, CUDA, and Apple Metal/MPS backends
• Full-spherical radial curls and conservative CFL selection
• Exponential conductive integration with a legacy trapezoidal option
• Configurable geodesic and radial grids, materials, sources, and anomalies
• Portable, versioned checkpoints with cross-backend restart
• Surface maps, radial sections, receiver traces, interactive 3-D views, and animations
• Analytic Maxwell verification and Simpson–Taflove reproduction workflows

Quick start

Python 3.11 or newer is required.

uv sync --extra test --extra visualization --extra pytorch
uv run ionosphere --steps 200

For repeatable runs, copy the provided TOML configuration and edit it instead of repeating command-line options:

cp configs/ionosphere.example.toml run.toml
uv run ionosphere --config run.toml

Explicit command-line options override values from the file. See the command-line reference for the simulation and visualization table layout.

Minimal Python usage:

from ionosphere_fdtd import GeodesicFDTD, GaussianCurrent, SimulationConfig

simulation = GeodesicFDTD(
    SimulationConfig(subdivision=2, radial_cells=24),
    source=GaussianCurrent(carrier_frequency_hz=20.0),
)
simulation.step(1000)
print(simulation.diagnostics())

Documentation

• User manual
• Installation
• Quick start
• Command-line reference
• Simulation configuration
• Materials and sources
• Backends and performance
• Visualization and output
• Troubleshooting
• Verification: analytic solutions, Simpson–Taflove 2004, and Simpson–Taflove 2006
• Backend benchmarks

Development

uv run --extra test --extra visualization --extra pytorch pytest -q

Verification workflows are kept outside the distributed runtime package and run from a source checkout. The linked verification reports contain their commands, acceptance criteria, and current results.

References

1. D. A. Randall et al., “Climate Modeling with Spherical Geodesic Grids,” Computing in Science & Engineering, 4(5), 32–41, 2002.
2. J. J. Simpson and A. Taflove, “Three-dimensional FDTD modeling of impulsive ELF propagation about the entire Earth-sphere,” IEEE TAP, 52(2), 443–451, 2004.
3. J. J. Simpson, R. P. Heikes, and A. Taflove, “FDTD modeling of a novel ELF radar for major oil deposits using a three-dimensional geodesic grid of the Earth-ionosphere waveguide,” IEEE TAP, 54(6), 1734–1741, 2006.
4. A. Taflove and S. C. Hagness, Computational Electrodynamics: The Finite-Difference Time-Domain Method, 3rd ed., Chapter 3, 2005.

License

Copyright 2026 Kyungwon Chun.

Licensed under the Apache License 2.0. See NOTICE for the project copyright notice.