plot_dbr_couplings

Plot physical DBR couplings from separation-indexed Green tensors.

The optional rx_selection config selects arbitrary, disjoint separations while preserving the requested order. For example, a single plot can combine near-field and far-field samples:

rx_selection:
  values_nm: [1, 2, 5, 10, 20, 50, 500, 600, 700, 1000]
  nearest: false
  tolerance_nm: 1.0e-9

Use values_nm: null (the default) to retain the complete input Rx_nm grid. Set nearest: true only when requested values need not lie exactly on the stored grid; requested values, selected values, source indices, and deltas are then recorded in the output provenance.

mqed.analysis.plot_dbr_couplings.compute_dbr_couplings(G_slice: numpy.ndarray, Rx_nm: numpy.ndarray, energy_eV: float, p_donor: numpy.ndarray, p_acceptor: numpy.ndarray, mu_D_debye: float, mu_A_debye: float) → Dict[str, numpy.ndarray]

Compute physical DBR couplings versus separation.

Parameters:

• G_slice – Selected Green tensor slice, shape (K, 3, 3).

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

• energy_eV – Selected transition energy in eV.

• p_donor – Donor dipole unit vector, shape (3,).

• p_acceptor – Acceptor dipole unit vector, shape (3,).

• mu_D_debye – Donor dipole magnitude in Debye.

• mu_A_debye – Acceptor dipole magnitude in Debye.

Returns:

Dictionary containing projected Green data and signed/absolute V_eV, hbarGamma_eV, and Gamma_s_inv arrays.

mqed.analysis.plot_dbr_couplings.main(cfg: Any) → None

Hydra CLI entry point for DBR coupling plotting.

mqed.analysis.plot_dbr_couplings.resolve_dipole_orientations(cfg: Any) → Tuple[numpy.ndarray, numpy.ndarray, float, float, float, float]

Resolve donor and acceptor dipole unit vectors from theta/phi config.

mqed.analysis.plot_dbr_couplings.run_from_config(cfg: Any, output_dir: Path, original_cwd: Path | None = None) → Path

Run DBR coupling analysis from a Hydra/OmegaConf-compatible config.

Parameters:

• cfg – Configuration mapping or OmegaConf object.

• output_dir – Directory where HDF5, CSV, and PNG files are written.

• original_cwd – Base directory for resolving relative input paths.

Returns:

Path to the written HDF5 result file.

mqed.analysis.plot_dbr_couplings.select_energy_index(energy_eV: numpy.ndarray, selection_cfg: Any) → Dict[str, Any]

Select one energy grid point by index or requested value.

Parameters:

• energy_eV – One-dimensional available energy grid in eV.

• selection_cfg – Mapping with either index or value_eV. When selecting by value, nearest controls whether the nearest grid point may be used instead of requiring an exact/tolerance match.

Returns:

Provenance dictionary with selected index/value and request metadata.

mqed.analysis.plot_dbr_couplings.select_rx_indices(Rx_nm: numpy.ndarray, selection_cfg: Any) → Dict[str, Any]

Select ordered separation-grid rows by indices or physical values.

Configure rx_selection.values_nm with any disjoint near-/far-field values, for example [1, 2, 5, 10, 50, 500, 700, 1000]. Exact matching within tolerance_nm is the default. With nearest: true, each requested value maps to its nearest stored grid point. Alternatively, rx_selection.indices selects source rows directly. Requested order and duplicates are preserved. Null or empty selections retain the full grid.

Parameters:

• Rx_nm – One-dimensional available separation grid in nm.

• selection_cfg – Mapping containing either indices or values_nm, plus optional nearest and tolerance_nm settings.

Returns:

Provenance dictionary containing ordered selected indices/values, requested values, matching deltas, and selection settings.