dgf_data

HDF5 I/O for dyadic Green’s function data.

Four storage layouts are supported, distinguished by the HDF5 attribute gf_layout on the root group:

Separation-indexed (gf_layout = "separation", legacy default)

The Green’s function is stored as (M, K, 3, 3) where M is the number of energy points and K is the number of distinct inter-emitter separations Rx. This layout exploits translational symmetry: all emitter pairs at the same separation share the same tensor.

Applicable to: planar surfaces (2-layer, N-layer), any geometry with full in-plane translational symmetry.

Datasets:

green_function_total   (M, K, 3, 3)   complex128
green_function_vacuum  (M, K, 3, 3)   complex128
energy_eV              (M,)           float64
Rx_nm                  (K,)           float64
position_fixed         group  {zD_meters, zA_meters}
Pair-indexed (gf_layout = "pair")

The Green’s function is stored as (M, N, N, 3, 3) where N is the number of emitters. Entry [m, i, j, :, :] is the full dyadic G(r_i, r_j, ω_m). No symmetry is assumed.

Applicable to: nanorods, nanoparticles, arbitrary geometries — any case where translational symmetry is broken.

Datasets:

green_function_total   (M, N, N, 3, 3)   complex128
green_function_vacuum  (M, N, N, 3, 3)   complex128
energy_eV              (M,)              float64
emitter_positions_nm   (N, 3)            float64
emitter_orientations   (N, 3)            float64, optional
position_fixed         group  {zD_meters, zA_meters}
Scan-indexed (gf_layout = "scan")

The Green’s function is stored as (M, P, 3, 3) where P is the number of explicit observer positions for one fixed source position. No translational symmetry is assumed between observer points.

Applicable to: spherical particles/cavities or arbitrary point scans.

Datasets:

green_function_total   (M, P, 3, 3)   complex128
green_function_vacuum  (M, P, 3, 3)   complex128
energy_eV              (M,)           float64
observer_positions_nm  (P, 3)         float64
source_position_nm     (3,)           float64
position_fixed         group  {zD_meters, zA_meters}
Projected circulant ring (gf_layout = "ring_circulant")

For an evenly spaced emitter ring around a concentric spherical medium, the dipole-projected scalar Green matrix is circulant. Only its observer-0 row is stored, with shape (M, N). Entry [m, k] represents the projected coupling from source k to observer 0; the full scalar matrix follows as G[m, i, j] = row[m, (j-i) mod N].

Backward compatibility: files written by older planar code (no gf_layout attribute) are treated as separation-indexed, while older Mie scan files are recognized from their explicit position datasets and G_total aliases.

mqed.utils.dgf_data.load_gf_h5(h5_path: str, *, max_ring_bytes: int = 2147483648) → Dict[str, numpy.ndarray][source]

Load dyadic Green’s function from HDF5, auto-detecting layout.

Returns:

Common keys:

  • G_total: Total Green’s function array.

  • G_vac: Vacuum Green’s function array.

  • energy_eV: Energy array, shape (M,).

  • zD: Source z-position (meters).

  • zA: Observer z-position (meters).

  • gf_layout: "separation", "pair", "scan", or "ring_circulant".

Separation-indexed adds:

  • Rx_nm: Separation grid, shape (K,).

Pair-indexed and ring-circulant add:

  • emitter_positions_nm: Emitter coordinates, shape (N, 3).

  • emitter_orientations: Optional emitter orientations, shape (N, 3).

Return type:

Dictionary with keys that depend on the layout

mqed.utils.dgf_data.save_gf_h5(h5_path: str, Gtot: np.ndarray, Gvac: np.ndarray, E: np.ndarray, Rxnm: np.ndarray, zD: float, zA: float, *, Gstructure: np.ndarray | None = None, G_scattering_te: np.ndarray | None = None, G_scattering_tm: np.ndarray | None = None, attrs: Dict[str, Any] | None = None) → None[source]

Save separation-indexed Green’s function arrays to HDF5.

Parameters:

  • h5_path – Output file path.

  • Gtot – Total Green’s function, shape (M, K, 3, 3).

  • Gvac – Vacuum Green’s function, shape (M, K, 3, 3).

  • E – Energy grid in eV, shape (M,).

  • Rxnm – Separation grid in nm, shape (K,).

  • zD – Source (donor) z-position in meters.

  • zA – Observer (acceptor) z-position in meters.

  • Gstructure – Optional scattering/structure Green tensor, same shape as Gtot.

  • G_scattering_te – Optional TE scattering tensor, same shape as Gtot.

  • G_scattering_tm – Optional TM scattering tensor, same shape as Gtot.

  • attrs – Optional root attributes.

mqed.utils.dgf_data.save_gf_pair_h5(h5_path: str, Gtot: np.ndarray, Gvac: np.ndarray, E: np.ndarray, emitter_positions_nm: np.ndarray, zD: float, zA: float, Gstructure: np.ndarray | None = None, wavelength_m: np.ndarray | None = None, observer_region: np.ndarray | None = None, attrs: Dict[str, Any] | None = None, emitter_orientations: np.ndarray | None = None) → None[source]

Save pair-indexed Green’s function arrays to HDF5.

Parameters:

  • h5_path – Output file path.

  • Gtot – Total Green’s function, shape (M, N, N, 3, 3).

  • Gvac – Vacuum Green’s function, shape (M, N, N, 3, 3).

  • E – Energy grid in eV, shape (M,).

  • emitter_positions_nm – 3D positions of all emitters in nm, shape (N, 3).

  • zD – Source z-position in meters (reference height).

  • zA – Observer z-position in meters (reference height).

  • emitter_orientations – Optional normalized emitter dipole orientations, shape (N, 3).

mqed.utils.dgf_data.save_gf_ring_circulant_h5(h5_path: str, Gtot: np.ndarray, Gvac: np.ndarray, E: np.ndarray, emitter_positions_nm: np.ndarray, emitter_orientations: np.ndarray, zD: float, zA: float, *, Gstructure: np.ndarray | None = None, wavelength_m: np.ndarray | None = None, observer_region: np.ndarray | None = None, attrs: Dict[str, Any] | None = None) → None[source]

Save a dipole-projected circulant Green row for a symmetric ring.

The Green arrays have shape (M, N) and already include the left and right emitter-orientation projections. This layout is not a dyadic tensor and must only be used when cyclic symmetry has been established.