geopulse.earth.structured_2d

2-D structured Earth models.

Two flavours live here:

CoastalCorrection2D — a semi-analytic coast-effect wrapper that interpolates between a land Layered1D and an ocean Layered1D model based on distance from the coast, producing a TensorImpedance. Fast, closed-form, captures the classic ocean/continent contrast that dominates coastal GIC risk. This is what operational GIC codes typically use in place of a true 2-D finite-difference solve.
Structured2D — placeholder for a proper finite-difference / finite-element 2-D MT solver (TE/TM modes on a discretised cross-section). Deferred; raises NotImplementedYetError.

Coordinate convention (both classes)

The coast is aligned with the y axis (east). Distance from the coast d_m is measured along x (north), positive inland, negative seaward. Under this frame the impedance tensor is anti-diagonal:

\[\begin{split}\tilde{Z}(ω) = \begin{bmatrix} 0 & Z_\mathrm{TE}(ω) \\ -Z_\mathrm{TM}(ω) & 0 \end{bmatrix}\end{split}\]

where TE (E-parallel-to-coast) and TM (E-perpendicular-to-coast) modes decouple and can be computed independently.

For CoastalCorrection2D the smooth interpolation used is:

Z_TE(d, ω) = Z_land(ω) + [Z_ocean(ω) − Z_land(ω)] · f_TE(d, ω)
Z_TM(d, ω) = Z_land(ω) + [Z_ocean(ω) − Z_land(ω)] · f_TM(d, ω)

with f_TE(d, ω) = ½ [1 − tanh(d / δ(ω))], f_TM similar but with a shorter decay length (TM is more strongly perturbed near a conductivity contrast per Weaver 1994 and Boteler-Pirjola 1998), and δ(ω) = √(2 / (ω μ₀ σ_eff)) the skin depth at the geometric-mean surface conductivity σ_eff = √(σ_land · σ_ocean). Limits check:

d → +∞   ⇒   Z_TE, Z_TM → Z_land
d → −∞   ⇒   Z_TE, Z_TM → Z_ocean
d = 0    ⇒   Z_TE, Z_TM = (Z_land + Z_ocean) / 2

This is not a substitute for a full 2-D FD MT computation at percent-level accuracy — the goal is a defensible, closed-form correction that captures the right qualitative behaviour and asymptotic limits, and that returns a proper TensorImpedance so downstream E-field computations exercise the tensor code path.

References

Classes

`CoastalCorrection2D`(land_model, ocean_model, ...)	Semi-analytic coast-effect 2-D Earth model.
`Structured2D`()	True 2-D finite-difference MT solver — STUB (deferred WP).

class geopulse.earth.structured_2d.CoastalCorrection2D(land_model, ocean_model, distance_from_coast_m, tm_decay_ratio=0.7)[source]

Bases: EarthModel

Semi-analytic coast-effect 2-D Earth model.

Interpolates between two 1-D reference models (land and ocean) via a tanh-shaped coupling function of distance from the coast, producing a TensorImpedance at each frequency.

Parameters:

land_model (Layered1D) – Layered 1-D model for the land side (well inland). Provides the far-field d → +∞ asymptote.
ocean_model (Layered1D) – Layered 1-D model for the ocean side (well offshore). Typically a thin high-conductivity seawater layer over the same deep conductivity structure. Provides the d → −∞ asymptote.
distance_from_coast_m (float) – Distance of the observation site from the coastline, in metres. Positive inland, negative seaward. 0 sits exactly at the coast.
tm_decay_ratio (float) – Ratio of TM to TE decay length L_TM / L_TE. Smaller → TM transitions more sharply than TE. Default 0.7 matches the Boteler-Pirjola (1998) observation that TM is more perturbed than TE near the interface.

Notes

tier == 2. Coordinate frame: coast along y (east); x (north) points inland. The tensor is anti-diagonal.

Examples

>>> import numpy as np
>>> from geopulse.earth.base import ConductivityLayer
>>> from geopulse.earth.layered_1d import Layered1D
>>> land = Layered1D([ConductivityLayer(np.inf, 0.001)])
>>> ocean = Layered1D([
...     ConductivityLayer(1_000.0, 3.3),
...     ConductivityLayer(np.inf, 0.001),
... ])
>>> coast = CoastalCorrection2D(land, ocean, distance_from_coast_m=0.0)
>>> imp = coast.compute_impedance(np.array([1e-3, 1e-2, 1e-1]))
>>> imp.rank
2

property tier: int: Return 2.

compute_impedance(freqs_Hz)[source]

Compute the surface impedance tensor per the coast-effect model.

Parameters:: freqs_Hz (ndarray) – Frequencies in Hz. Shape (n_freqs,). Must be non-negative; DC returns a zero tensor (no plane-wave response at ω = 0).
Return type:: Impedance
Returns:: TensorImpedance – Anti-diagonal 2×2 impedance tensor per frequency.

class geopulse.earth.structured_2d.Structured2D[source]

Bases: EarthModel

True 2-D finite-difference MT solver — STUB (deferred WP).

Discretises a 2-D cross-section, solves TE and TM Maxwell modes on the grid with proper boundary conditions, and extracts the impedance tensor at surface locations. See CoastalCorrection2D for the pragmatic closed-form alternative that is available now.

property tier: int: Return 2.

compute_impedance(freqs_Hz)[source]

Not yet implemented — use CoastalCorrection2D instead.

Return type:: Impedance
Parameters:: freqs_Hz (ndarray)