geopulse.earth.impedance

Surface-impedance abstraction — the polymorphism spine of GeoPulse.

The surface impedance Z relates the horizontal magnetic field B to the geoelectric field E. Its mathematical rank depends on Earth-model complexity:

  • 1-D — Z(ω) is a complex SCALAR per frequency:

    E_x =  (Z / μ₀) · B_y,    E_y = -(Z / μ₀) · B_x

  • 2-D — Z̃(ω) is a 2×2 TENSOR per frequency:

    E_i(ω) = Σ_j Z_ij(ω) · B_j(ω) / μ₀

  • 3-D — Z̃(r, r', ω) is a spatial KERNEL (convolution):

    E(r, ω) = ∬ Z̃(r, r', ω) · B(r', ω) d²r' / μ₀

All three implement Impedance.apply() and return (Ex_f, Ey_f). The efield layer calls apply() blindly.

HDF5 storage

References

Classes

Impedance(freqs_Hz)

Abstract base class for surface impedance.

KernelImpedance(freqs_Hz, Z_kernel)

3-D volumetric-response kernel Z̃(r, r', ω) — STUB (WP3).

ScalarImpedance(freqs_Hz, Z_values)

1-D scalar impedance Z(ω).

TensorImpedance(freqs_Hz, Z_tensor)

2-D magnetotelluric impedance tensor Z̃(ω) — 2×2 per frequency.
class geopulse.earth.impedance.Impedance(freqs_Hz)[source]

Bases: ABC

Abstract base class for surface impedance.

Parameters:

freqs_Hz (ndarray) – Frequency array in Hz. Cast internally to float64. Shape: (n_freqs,).

freqs_Hz

The stored frequency array.

Type:

numpy.ndarray

abstractmethod apply(Bx_f, By_f)[source]

Apply the impedance to frequency-domain B-field, returning E-field.

Parameters:

  • Bx_f (ndarray) – FFT of Bx in Tesla. Shape: (n_freqs,).

  • By_f (ndarray) – FFT of By in Tesla. Shape: (n_freqs,).

Return type:

tuple[ndarray, ndarray]

Returns:

  • Ex_f (numpy.ndarray) – FFT of Ex in V/m. Shape matches subclass semantics.

  • Ey_f (numpy.ndarray) – FFT of Ey in V/m. Shape matches subclass semantics.

abstract property rank: int

0 for scalar (1-D), 2 for tensor (2-D), 4 for kernel (3-D).

Type:

Rank marker

abstractmethod to_hdf5(group)[source]

Serialise impedance data to an HDF5 group.

Return type:

None

Parameters:

group (Group)

abstractmethod classmethod from_hdf5(group)[source]

Deserialise impedance data from an HDF5 group.

Return type:

Impedance

Parameters:

group (Group)

class geopulse.earth.impedance.ScalarImpedance(freqs_Hz, Z_values)[source]

Bases: Impedance

1-D scalar impedance Z(ω).

For a horizontally layered Earth under plane-wave excitation, the surface impedance is a single complex number per frequency. This is the standard magnetotelluric relation for the 1-D case.

Parameters:

  • freqs_Hz (ndarray) – Frequency array in Hz. Shape: (n_freqs,).

  • Z_values (ndarray) – Complex impedance values in Ohms. Shape: (n_freqs,). Cast to complex128 on construction.

Raises:

ShapeMismatchError – If Z_values.shape does not equal freqs_Hz.shape.

Notes

The applied relation is [1]:

E_x(ω) =  (Z(ω) / μ₀) · B_y(ω)
E_y(ω) = -(Z(ω) / μ₀) · B_x(ω)

Examples

>>> import numpy as np
>>> freqs = np.array([1e-3, 1e-2, 1e-1])
>>> Z = np.array([1+1j, 3+3j, 10+10j])
>>> imp = ScalarImpedance(freqs, Z)
>>> Ex, Ey = imp.apply(np.ones(3), np.ones(3))
>>> Ex.shape
(3,)
apply(Bx_f, By_f)[source]

Apply the 1-D plane-wave MT relation E = (Z/μ₀) · B_perp.

Parameters:

  • Bx_f (ndarray) – FFT of the horizontal B-field components in Tesla. Shape: (n_freqs,).

  • By_f (ndarray) – FFT of the horizontal B-field components in Tesla. Shape: (n_freqs,).

Return type:

tuple[ndarray, ndarray]

Returns:

Ex_f, Ey_f (numpy.ndarray) – FFT of the horizontal E-field components in V/m. Shape: (n_freqs,).

Raises:

ShapeMismatchError – If Bx_f or By_f do not have the same length as freqs_Hz.

property rank: int

Return 0 — scalar per frequency.

to_hdf5(group)[source]

Serialise to an HDF5 group with a schema-version attribute.

Layout:

group/
  attrs:
    impedance_type = "scalar_1d"
    schema_version = 1
  freqs_Hz         dataset
  Z_values         dataset (complex128)
Return type:

None

Parameters:

group (Group)

classmethod from_hdf5(group)[source]

Read a ScalarImpedance from an HDF5 group.

Return type:

ScalarImpedance

Parameters:

group (Group)

class geopulse.earth.impedance.TensorImpedance(freqs_Hz, Z_tensor)[source]

Bases: Impedance

2-D magnetotelluric impedance tensor Z̃(ω) — 2×2 per frequency.

Applied relation (per frequency ω_i):

Ex(ω_i) = (Z[i,0,0] · Bx(ω_i) + Z[i,0,1] · By(ω_i)) / μ₀
Ey(ω_i) = (Z[i,1,0] · Bx(ω_i) + Z[i,1,1] · By(ω_i)) / μ₀

Shape convention: Z_tensor[i, :, :] is the 2×2 tensor at freqs_Hz[i]. A 1-D isotropic Earth is the special case Z_tensor[i] = [[0, Z], [-Z, 0]].

Parameters:

  • freqs_Hz (ndarray) – Frequency array in Hz. Shape (n_freqs,).

  • Z_tensor (ndarray) – Complex impedance tensor. Shape (n_freqs, 2, 2).

Raises:

ShapeMismatchError – If Z_tensor.shape does not equal (n_freqs, 2, 2).

apply(Bx_f, By_f)[source]

Apply the 2×2 tensor relation E(ω) = Z̃(ω) · B(ω) / μ₀.

Parameters:

  • Bx_f (ndarray) – FFT of horizontal B-field components in Tesla. Shape (n_freqs,).

  • By_f (ndarray) – FFT of horizontal B-field components in Tesla. Shape (n_freqs,).

Return type:

tuple[ndarray, ndarray]

Returns:

Ex_f, Ey_f (numpy.ndarray) – FFT of horizontal E-field components in V/m. Shape (n_freqs,).

Raises:

ShapeMismatchError – If either input does not match freqs_Hz in shape.

property rank: int

Return 2 — 2×2 tensor per frequency.

to_hdf5(group)[source]

Serialise to an HDF5 group with a schema-version attribute.

Layout:

group/
  attrs:
    impedance_type = "tensor_2d"
    schema_version = 1
  freqs_Hz      dataset
  Z_tensor      dataset (complex128, shape (n_freq, 2, 2))
Return type:

None

Parameters:

group (Group)

classmethod from_hdf5(group)[source]

Read a TensorImpedance from an HDF5 group.

Return type:

TensorImpedance

Parameters:

group (Group)

class geopulse.earth.impedance.KernelImpedance(freqs_Hz, Z_kernel)[source]

Bases: Impedance

3-D volumetric-response kernel Z̃(r, r', ω) — STUB (WP3).

Shape convention: (n_freqs, n_r, n_r, 2, 2). In practice the kernel will be sparse or block-structured and use chunked HDF5 storage.

Parameters:

  • freqs_Hz (np.ndarray)

  • Z_kernel (np.ndarray)

apply(Bx_f, By_f)[source]

Not yet implemented (WP3).

Return type:

tuple[ndarray, ndarray]

Parameters:
property rank: int

Return 4 — spatial kernel per frequency.

to_hdf5(group)[source]

Not yet implemented (WP3).

Return type:

None

Parameters:

group (Group)

classmethod from_hdf5(group)[source]

Not yet implemented (WP3).

Return type:

KernelImpedance

Parameters:

group (Group)