mxl-multimode

name	mxl-multimode
description	This skill should be used when users need the MaxwellLink multimode Fabry-Pérot cavity solver to study a spatial grid of molecules coupled to many photonic modes (mesoscale VSC), in either socket or embedded mode.

Multimode Fabry-Pérot cavity workflows (MaxwellLink)

When to use

• Use mxl.MultiModeSimulation paired with mxl.FabryPerotCavity when the physics requires a 2D molecular grid coupled to many photon modes (mesoscale VSC, polariton dispersion, planar Fabry-Pérot dynamics). For 1-mode prototyping prefer skills/mxl-singlemode/SKILL.md; for full FDTD prefer skills/mxl-meep/SKILL.md.
• Reference: TE Li, J. Chem. Theory Comput. 20, 7016 (2024).

Configure the cavity geometry (FabryPerotCavity)

• Required: frequency_au (cavity reference angular frequency at k_∥=0), delta_omega_x_au, delta_omega_y_au (planar dispersion spacings; mode frequencies are sqrt(omega_c^2 + (l_x·dωx)^2 + (l_y·dωy)^2)).
• Mode count: n_mode_x, n_mode_y (cavity modes per axis).
• Molecular grid: provide either n_grid_x/n_grid_y (uniform grid, overrides explicit lists) or x_grid_1d/y_grid_1d (explicit fractional positions in [0, 1] of Lx, Ly). n_repeat_x/n_repeat_y stack multiple molecules per spatial site.
• Coupling: coupling_strength is the prefactor ε for the lowest mode; per-mode couplings are auto-rescaled as ε_k = ε · ω_k / min ω_k. coupling_axis is a case-insensitive union of "x", "y", "z".
• Boundaries: abc_cutoff (fractional grid units, default 0.0) enables an absorbing-boundary smooth window on large planar grids to kill unphysical reflections — recommended whenever n_grid_x*n_grid_y is large.

Configure the simulation (MultiModeSimulation)

• Required: dt_au, cavity_geometry=cavity (must be a FabryPerotCavity instance — the simulation transparently exposes n_mode, n_grid, omega_k, ftilde_k, ... via attribute lookup).
• Molecules: pass an iterable of mxl.Molecule matching n_grid = n_grid_x * n_grid_y * n_repeat_x * n_repeat_y. Socket and embedded molecules can be mixed. For socket runs, all molecules must share one SocketHub.
• Cavity dissipation: damping_au is a deterministic exponential damping on pc every step. Always-on; 0.0 disables.
• Light-matter physics: include_dse=True (default) is required for real-molecule drivers (LAMMPS, Psi4). Set False only for model drivers (TLS, QuTiP) when you intentionally want to drop dipole self-energy.
• VV interop: molecule_half_step=True extrapolates molecular response from half-step data — only set this if the molecular driver returns half-step VV data.
• Initial conditions: qc_initial, pc_initial (shape (n_mode, 3)), mu_initial, dmudt_initial (shape (n_grid, 3)). All default to zeros and are then passed through the initializer.
• Baseline shift: shift_dipole_baseline=True subtracts the initial dipole from every subsequent dipole — useful when permanent dipoles are large in strong-coupling runs.

Initializer / thermostat (NVE vs NVT)

The thermal knobs are now objects, not scalar kwargs. Old-style T_initial_au / NVT_T_au / langevin_tau_au / thermostat_seed no longer exist.

• Defaults are initializer=DummyInitializer() and thermostat=DummyThermostat() (zero IC, NVE).
• For an NVT thermal IC, use initializer=MaxwellBoltzmannInitializer(temperature_au=T_au, random_seed=...). It only fills qc/pc slots that are still all-zero, so user-provided qc_initial/pc_initial win.
• For a Langevin thermostat, use thermostat=LangevinThermostat(temperature_au=T_au, dt_au=dt_au, tau_au=tau_au, random_seed=...). Note dt_au must match the simulation dt_au.
• Pair the same random_seed across initializer + thermostat for reproducibility. Use from maxwelllink.units import AU_TO_K for K↔a.u. conversions.

Drives

• Photon-side pulse: pick mode indices via excited_mode_list=[i, ...], give a constant or callable(t_au) as photon_pulse_drive, and choose photon_pulse_axis (default "y").
• Molecule-side pulse: pick grid indices via excited_grid_list=[i, ...], with molecule_pulse_drive (constant or callable) and molecule_pulse_axis (default "y").
• K-parallel source: use from maxwelllink.tools import gaussian_pulse, k_parallel_pulse; build source = k_parallel_pulse(cavity=cavity, target="molecule" or "photon", envelope=gaussian_pulse(...) or 1.0, omega_au=..., k_parallel_au=..., direction="x" or "y", center=(...), size=(...), amplitude_au=...). For target="molecule", pass excited_grid_list=source.excited_grid_list and molecule_pulse_drive=source; for target="photon", pass excited_mode_list=source.excited_mode_list and photon_pulse_drive=source.
• Both are optional and additive; passing an empty list disables that channel.

Run + recording

• sim.run(...) accepts until XOR steps. Recording is configured on run(), not the constructor:
  • record_history=True (default) keeps per-record arrays in memory.
  • record_to_disk=True requires disk_folder_address plus exactly one of npz_filename / h5_filename. NPZ uses memmap-backed temp files that are compacted on finalize; H5 writes directly via h5py.
  • record_list selects fields: ["all"] or any subset of "time", "qc", "pc", "photon_drive", "molecule_pulse", "energy", "effective_efield", "molecule_response", "molecule_dipole". Passing [] or None disables recording.
  • record_every_steps thins; record_max_steps caps the on-disk allocation (defaults to steps // record_every_steps).
• After run(), in-memory arrays are exposed as simu.<name>_history (e.g. simu.qc_history, simu.molecule_dipole_history).

References

• Recipes: skills/mxl-multimode/references/multimode_run_recipes.md
• Docs: docs/source/em_solvers/multimode_cavity.rst
• Tutorial notebook: docs/source/tutorials/notebook/11_multimode_sho.ipynb