ddi_matrix¶

Dipole–dipole interaction (DDI) matrices for Lindblad dynamics.

Two Green’s function input formats are supported:

Separation-indexed G_slice of shape (K, 3, 3): One tensor per distinct separation Rx. Exploits translational symmetry: all emitter pairs (i, j) with the same |i−j| share the same Green’s function. Appropriate for planar surfaces and any geometry with in-plane translational symmetry.
Pair-indexed G_pair of shape (N, N, 3, 3): One tensor per emitter pair. No symmetry assumed. Required for nanorods, nanoparticles, or any geometry where the self-term (Purcell factor) and inter-site coupling depend on absolute emitter position — not just their separation.

The public entry point build_ddi_matrix() auto-dispatches based on which argument is provided. The legacy function build_ddi_matrix_from_Gslice() is preserved for backward compatibility and is called internally for separation-indexed data.

mqed.Lindblad.ddi_matrix._resolve_orientations(mode: str, N_mol: int, *, uD: numpy.ndarray | None = None, uA: numpy.ndarray | None = None, U_list: numpy.ndarray | None = None, theta_deg: float | None = None, phi_deg: float | None = None, disorder_sigma_phi_deg: float | None = None, disorder_seed: int | None = None) → tuple[source]¶

Resolve dipole orientations for stationary or disorder mode.

Returns:: For stationary: ("stationary", uD(3,), uA(3,), None) For disorder: ("disorder", None, None, U(N,3))
Return type:: (mode_flag, uD, uA, U)

mqed.Lindblad.ddi_matrix.build_ddi_matrix(energy_emitter: float, N_mol: int, mu_D_debye: float, mu_A_debye: float | None = None, *, G_slice: numpy.ndarray | None = None, Rx_nm: numpy.ndarray | None = None, d_nm: float | None = None, G_pair: numpy.ndarray | None = None, mode: str = 'stationary', uD: numpy.ndarray | None = None, uA: numpy.ndarray | None = None, U_list: numpy.ndarray | None = None, theta_deg: float | None = None, phi_deg: float | None = None, disorder_sigma_phi_deg: float | None = None, disorder_seed: int | None = None) → tuple[source]¶

Build DDI matrices, auto-dispatching by Green’s function format.

Provide either G_pair (pair-indexed) or the trio (G_slice, Rx_nm, d_nm) (separation-indexed). If both are given, G_pair takes precedence.

Parameters:

energy_emitter – Emitter transition energy in eV.
N_mol – Number of emitters.
mu_D_debye – Donor dipole moment (Debye).
mu_A_debye – Acceptor dipole; defaults to donor value.
G_slice – Separation-indexed (K, 3, 3) Green’s function.
Rx_nm – Separation grid (K,) in nm.
d_nm – Lattice spacing in nm.
G_pair – Pair-indexed (N, N, 3, 3) Green’s function.
mode – "stationary" or "disorder".
kwargs) ((orientation) – see individual builders.

Returns:

(V_eV, hbarGamma_eV) — both (N, N) real arrays.

mqed.Lindblad.ddi_matrix.build_ddi_matrix_from_Gpair(G_pair: numpy.ndarray, energy_emitter: float, N_mol: int, mu_D_debye: float, mu_A_debye: float | None = None, *, mode: str = 'stationary', uD: numpy.ndarray | None = None, uA: numpy.ndarray | None = None, U_list: numpy.ndarray | None = None, theta_deg: float | None = None, phi_deg: float | None = None, disorder_sigma_phi_deg: float | None = None, disorder_seed: int | None = None) → tuple[source]¶

Build DDI matrices from a pair-indexed Green’s function.

Each emitter pair (i, j) has its own G(r_i, r_j, ω) tensor. No translational symmetry is assumed — the diagonal (self-term, Purcell factor) can differ for each emitter.

Physics (same as separation-indexed):

\[V_{ij} = -\frac{\omega^2}{\epsilon_0 c^2}\, \boldsymbol{\mu}_i \cdot \Re\,G(r_i, r_j) \cdot \boldsymbol{\mu}_j\]

\[\hbar\Gamma_{ij} = \frac{2\omega^2}{\epsilon_0 c^2}\, \boldsymbol{\mu}_i \cdot \Im\,G(r_i, r_j) \cdot \boldsymbol{\mu}_j\]

Parameters:

G_pair – Shape (N, N, 3, 3) complex — full pair-indexed dyadic Green’s function for a single energy.
energy_emitter – Emitter transition energy in eV.
N_mol – Number of emitters.
mu_D_debye – Donor dipole moment (Debye).
mu_A_debye – Acceptor dipole moment (Debye); defaults to donor.
mode – "stationary" or "disorder".
uD – Orientation unit vectors (stationary mode).
uA – Orientation unit vectors (stationary mode).
U_list – Orientation controls (disorder mode).
theta_deg – Orientation controls (disorder mode).
phi_deg – Orientation controls (disorder mode).
disorder_* – Orientation controls (disorder mode).

Returns:

(V_eV, hbarGamma_eV) — both (N, N) real arrays.

mqed.Lindblad.ddi_matrix.build_ddi_matrix_from_Gslice(G_slice: numpy.ndarray, Rx_nm: numpy.ndarray, energy_emitter: float, N_mol: int, d_nm: float, mu_D_debye: float, mu_A_debye=None, *, mode: str = 'stationary', uD: numpy.ndarray | None = None, uA: numpy.ndarray | None = None, U_list=None, theta_deg: None | float = None, phi_deg: None | float = None, disorder_sigma_phi_deg=None, disorder_seed=None)[source]¶

Build DDI matrices from a separation-indexed Green’s slice.

Exploits translational symmetry: G(r_i, r_j) depends only on |r_i − r_j|. All pairs at the same separation share the same tensor. The self-term at Rx = 0 is used for every diagonal element — valid only when the Purcell factor is site-independent (e.g. planar surfaces, N-layer slabs).

Parameters:

G_slice – Shape (K, 3, 3) complex — one tensor per separation.
Rx_nm – Shape (K,) — separations in nm. Must contain 0, d, 2d, ..., (N-1)d.
energy_emitter – Emitter energy in eV.
N_mol – Number of molecules.
d_nm – Lattice spacing in nm.
mu_D_debye – Donor dipole moment (Debye).
mu_A_debye – Acceptor dipole; defaults to donor value.
mode – "stationary" or "disorder".
uD – Orientation vectors (stationary mode).
uA – Orientation vectors (stationary mode).
U_list – Orientation controls (disorder mode).
theta_deg – Orientation controls (disorder mode).
phi_deg – Orientation controls (disorder mode).
disorder_* – Orientation controls (disorder mode).

Returns:

(V_eV, hbarGamma_eV) — both (N, N) real arrays.