mxl-multimode

Files (2)

• SKILL.md
• multimode_run_recipes.md · references/

SKILL.md (first lines)

# 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`

From TaoELi/MaxwellLink, GPL-2.0.

More from TaoELi/MaxwellLink