Configuration Reference

All MQED-QD simulations are configured through YAML files managed by Hydra. The configuration tree lives under configs/ and is organised into five directories, each corresponding to a stage of the workflow.

configs/
├── Dyadic_GF/      # Green's function computation
├── Lindblad/        # Quantum dynamics solver
├── analysis/        # Post-processing (FE & RET)
├── BEM/             # Boundary-element-method utilities
└── plots/           # Observable plotting

Every CLI command loads its default config automatically. You can override any parameter on the command line using Hydra’s dotlist syntax:

# Override a single key
mqed_GF simulation.energy_eV=2.0

# Override a nested key
mqed_GF simulation.integration.qmax=100

# Use a different config file
mqed_GF --config-name=My_GF

See the Hydra documentation for full override syntax including sweeps and multirun.

Dyadic_GF/ — Green’s Function Computation

Files: GF_Sommerfeld.yaml (default), My_GF.yaml

Used by the mqed_GF command (Dyadic Green’s Function via Sommerfeld Integrals).

material

Defines the dielectric function of the substrate.

Key	Type	Description
source_type	str	"excel" to load experimental data, or "constant" for a frequency-independent dielectric constant.
constant_value	complex	Dielectric constant when source_type: constant (e.g. -11.0+1.0j).
excel_config.filepath	str	Path to the Excel file containing the tabulated dielectric function.
excel_config.sheet_name	str	Sheet name inside the Excel file.

simulation

Controls the physical parameters and numerical integration.

Key	Type	Description
material	str	Human-readable material label (used in output filenames).
spectral_param	str	"energy_eV" or "wavelength_nm" — selects which spectral parameterisation to use.
energy_eV	float | dict	A single value (e.g. 1.864), or a range {start, stop, points} for a sweep.
wavelength_nm	float | dict	Same as energy_eV but in nanometers.
position.zD_nm	float	Donor height above the interface (nm).
position.zA	float	Acceptor height (same units as zD).
position.Rx_nm	dict	Lateral donor–acceptor separation sweep: {start, stop, points}.
integration.qmax	float	Upper cutoff for the Sommerfeld integral in-plane momentum.
integration.epsabs	float	Absolute tolerance for numerical quadrature.
integration.epsrel	float	Relative tolerance.
integration.limit	int	Maximum number of subintervals.
integration.split_propagating	bool	Whether to split the integral at the propagating/evanescent boundary for improved accuracy.

output

Key	Type	Description
filename	str	Output HDF5 filename template. Supports Hydra interpolation (e.g. ${simulation.material}_GF.h5).

Lindblad/ — Quantum Dynamics

Files: quantum_dynamics.yaml (default), quantum_dynamics_disorder.yaml, quantum_dynamics_nhse.yaml

Used by the mqed_QD command (Quantum Dynamics).

greens

Key	Type	Description
h5_path	str	Path to the cached Green’s function HDF5 file produced by mqed_GF.

simulation

Key	Type	Description
t_ps.start	float	Start time (ps).
t_ps.stop	float	End time (ps).
t_ps.output_step	float	Time step for saved output (ps).
Nmol	int	Number of molecules in the 1-D chain.
d_nm	float	Lattice spacing (nm).
lambda_nm	float	Transition wavelength (nm).
gf_method	str	"Fresnel" or "BEM" — which Green’s function to use.
mode	str	"stationary" or "disorder".
coupling_limit.enable	bool	If true, truncate the coupling matrices at a finite range.
coupling_limit.V_hop_radius	int	Maximum hopping range (sites) for the DDI matrix \(V_{\alpha\beta}\).
coupling_limit.Gamma_hop_radius	int	Maximum hopping range (sites) for the dissipation matrix \(\Gamma_{\alpha\beta}\).
coupling_limit.Gamma_rule	str	Strategy for truncating \(\Gamma\) (e.g. "match_V").
coupling_limit.keep_V_on_site	bool	Always keep the diagonal (\(\alpha = \beta\)) DDI entries.
coupling_limit.keep_Gamma_on_site	bool	Always keep the diagonal dissipation entries.
dipole.mu_D_debye	float	Donor transition dipole moment (Debye).
dipole.mu_A_debye	float	Acceptor transition dipole moment (Debye).
dipole.theta_deg	float	Polar angle of the dipole orientation (degrees).
dipole.phi_deg	float	Azimuthal angle of the dipole orientation (degrees).

observables

A list of observables to compute at each output time step. Each entry has:

Key	Type	Description
name	str	Observable label (used in output files).
kind	str	One of root_MSD, X_shift, X_shift2, IPR_site, pop_site, X_shift_cond, X_shift2_cond.
enabled	bool	Whether to compute this observable.
params	dict	Observable-specific parameters (e.g. {site: 0} for pop_site).

initial_state

Key	Type	Description
site_index	int	Index of the initially excited site.

solver

Key	Type	Description
method	str	"Lindblad" (full master equation) or "NonHermitian" (non-Hermitian Hamiltonian approximation).

Disorder and NHSE Variants

quantum_dynamics_disorder.yaml extends the base config with:

Key	Type	Description
disorder.n_realizations	int	Number of disorder realisations.
disorder.seed	int	Random seed for reproducibility.
disorder.n_jobs	int	Parallel workers (-1 for all cores).
disorder.save_each	bool	Save each realisation individually.
disorder_sigma_phi_deg	float	Standard deviation of orientational disorder (degrees).

quantum_dynamics_nhse.yaml adds a height parameter and uses gf_method: BEM with coupling_limit.enable: false (long-range coupling) for studying the non-Hermitian skin effect.

analysis/ — Post-Processing

Files: FE.yaml, RET.yaml

Used by mqed_FE and mqed_RET (Field Enhancement).

Both configs share the same structure. The main difference is that FE.yaml plots the real and imaginary components (\(V_{\alpha\beta}/V_{0,\alpha\beta}\) and \(\Gamma_{\alpha\beta}/\Gamma_{0,\alpha\beta}\)) separately, while RET.yaml plots the single enhancement factor \(\gamma\).

input_file

Key	Type	Description
input_file	str	Path to the cached Green’s function HDF5 file.

orientations

Key	Type	Description
donor.theta_deg	float	Donor dipole polar angle (degrees).
donor.phi_deg	float | str	Donor dipole azimuthal angle. Use "magic" for the magic angle.
acceptor.theta_deg	float	Acceptor dipole polar angle.
acceptor.phi_deg	float | str	Acceptor dipole azimuthal angle.

plot_settings

Key	Type	Description
save_plot	bool	Write the figure to disk.
dpi	int	Figure resolution.
x_range_nm	list	[min, max] lateral distance range to plot (nm).
components	list	["real", "imag"] (FE only). Omitted in RET.
xlabel, ylabel	str	Axis labels.
title_template	str	Title with {energy:.3f} placeholder.
legend.real_label	str	Legend entry for the real component (FE).
legend.imag_label	str	Legend entry for the imaginary component (FE).
legend.label	str	Single legend entry (RET).
xscale, yscale	str	"linear" or "log".
xlim, ylim	list	Axis limits [min, max].
filename_prefix	str	Output filename prefix.

BEM/ — Boundary Element Method

Files: compare_bem_dyadic.yaml, compare.yaml, compare_silver.yaml, compare_enhancement.yaml, compute_peff.yaml, reconstruct_GF.yaml

These configs drive the BEM validation and reconstruction utilities.

compute_peff.yaml

Compute the effective dipole moment from BEM near-field data.

Key	Type	Description
io.xlsx_path	str	Path to the BEM Excel export.
io.output_csv	str	Output CSV with fitted effective dipoles.
sim.lambdas_nm	float | list | dict	Wavelengths to process (single, list, or {start, stop, points}).
sim.Rx_min_nm	float	Minimum lateral distance for fitting.
dipole.p_test_Cm	float	Test dipole moment (C·m).
fit.drop_small_E0	bool	Exclude low-amplitude points from the fit.

reconstruct_GF.yaml

Reconstruct the full dyadic Green’s function from BEM data and effective dipoles.

Key	Type	Description
parameters.energy_eV	float	Photon energy (eV).
parameters.lambda_nm	float	Corresponding wavelength (nm).
parameters.zD_nm, zA_nm	float	Donor / acceptor heights (nm).
io.xlsx_path	str	BEM Excel export.
io.peff_path	str	Effective-dipole CSV from compute_peff.
io.output_file	str	Output HDF5 with reconstructed Green’s function.

compare*.yaml

Comparison and validation configs (compare.yaml, compare_silver.yaml, compare_bem_dyadic.yaml, compare_enhancement.yaml) share a common pattern:

• paths / io — Input files (BEM Excel, Fresnel HDF5, effective-dipole CSV).

• dipoles / dipole_frequency — Orientation and transition frequency.

• test — Numerical comparison tolerances (rtol, atol, enabled).

• plot — Full Matplotlib configuration: figsize, dpi, rcParams, series definitions with labels, colours, and line styles.

plots/ — Observable Plotting

Files: msd.yaml, sqrt_msd.yaml, pr.yaml, ipr.yaml

Used by mqed_plot_msd, mqed_plot_sqrt_msd, mqed_plot_pr, and mqed_plot_ipr (Plotting & Analysis).

All four configs follow the same pattern.

curves

A list of datasets to overlay. Each entry:

Key	Type	Description
label	str	Legend label.
use_latest_glob	str	Glob pattern to find the input HDF5 file (most recent match is used).
style	str	Matplotlib line style (e.g. "-", "--").
lw	float	Line width.
color	str	Line colour.

plot_settings

Key	Type	Description
save_plot	bool	Write figure to disk.
dpi	int	Figure resolution.
figsize	list	[width, height] in inches.
x_range_ps	list	[min, max] time range (ps).
xlabel, ylabel, title	str	Axis and title labels.
xscale, yscale	str	"linear" or "log".
xlim, ylim	list	Axis limits.
shade_std	bool	If true, plot shaded standard-deviation band (for disorder averaging).
x_scale_factor	float	Multiply x-axis values (e.g. for unit conversion).
font	dict	Font settings: family, labelsize, ticksize, legendsize, titlesize.
y_sci	dict	Scientific notation formatting for the y-axis (enabled, scilimits, use_math_text).