maxwelllink.em_solvers.multimode_cavity module

Multimode cavity electrodynamics for MaxwellLink.

This module defines a lightweight cavity simulator that treats the EM field as multiple damped harmonic oscillators coupled to MaxwellLink molecules. The simulation runs entirely in atomic units and can operate with both socket-connected and embedded (non-socket) molecular drivers.

class maxwelllink.em_solvers.multimode_cavity.FabryPerotCavity

Bases: object

Damped harmonic oscillators coupled to MaxwellLink molecules.

Under the dipole gauge, the total light-matter Hamiltonian is

\[H = H_{mol} + \frac{1}{2} p_{\rm c}^2 + \frac{1}{2} \sum_{k\lambda}\omega_{k\lambda, \rm c}^2 (q_{k\lambda, \rm c} + \frac{\varepsilon_{k\lambda}}{\omega_{k\lambda,\rm c}^2} \sum_i \mu_i \cdot f_{k\lambda}(r_i))^2\]

The cavity mode (classical harmonic oscillator) obeys

\[\ddot{q}_{k\lambda, \rm c} = -\omega_{k\lambda, \rm c}^{2}\, q_{k\lambda, \rm c} \; - \; \varepsilon_{k\lambda} \sum_i \mu_i \cdot f_{k\lambda}(r_i) \;-\; \gamma_{k\lambda, \rm c} \, p_{k\lambda, \rm c} \;+\; D_{k\lambda}(t),\]

where the effective electric field of this cavity mode is

\[E(t) = -\sum_{k\lambda} \varepsilon_{k\lambda} q_{k\lambda, \rm c}(t) - \frac{\varepsilon_{k\lambda}^2}{\omega_{k\lambda, \rm c}^2} \sum_i \mu_i(t) \cdot f_{k\lambda}(r_i),\]

where \(\varepsilon_{k\lambda}\) is effective coupling strength for different photon modes, \(f_{k\lambda}(r_i)\) is the cavity mode function evaluated at the position of the r_i. The second term in the electric field accounts for the dipole self-energy term if enabled.

All quantities are in atomic units.

__init__(frequency_au=None, coupling_strength=1.0, coupling_axis='xy', x_grid_1d=None, y_grid_1d=None, n_grid_x=None, n_grid_y=None, n_repeat_x=1, n_repeat_y=1, delta_omega_x_au=None, delta_omega_y_au=None, n_mode_x=1, n_mode_y=1, abc_cutoff=0.0)

Parameters:

• frequency_au (float) – Cavity angular frequency \(\omega_{\rm c}\) (a.u.).

• coupling_strength (float, default: 1.0) – Prefactor \(\varepsilon\).

• coupling_axis (str, default: "xy") – Component(s) of the molecular dipole used for coupling.

• x_grid_1d (list, optional) – 1D grid points for molecular bath coordinates along x-axis, in units of cavity length Lx. If None, defaults to [0.5] (single point at the center).

• y_grid_1d (list, optional) – 1D grid points for molecular bath coordinates along y-axis, in units of cavity length Ly. If None, defaults to [0.5] (single point at the center).

• n_grid_x (int, default: 1) – Number of grid points for molecular bath coordinates along x-axis, in units of cavity length Lx. If provided together with n_grid_y, it will override x_grid_1d and generate a uniform grid along x-axis. If x_grid_1d is provided, n_grid_x will be ignored.

• n_grid_y (int, default: 1) – Number of grid points for molecular bath coordinates along y-axis, in units of cavity length Ly. If provided together with n_grid_x, it will override y_grid_1d and generate a uniform grid along y-axis. If y_grid_1d is provided, n_grid_y will be ignored.

• n_repeat_x (int, default: 1) – Number of times to repeat the grid points along x-axis.

• n_repeat_y (int, default: 1) – Number of times to repeat the grid points along y-axis.

• delta_omega_x_au (float, default: 0.0) – Frequency spacing along x-axis for cavity modes, in atomic units. The cavity mode frequencies are calculated as \(\omega_{k} = \sqrt{\omega_{\rm c}^2 + (l_x \Delta\omega_x)^2 + (l_y \Delta\omega_y)^2}\) where \(l_x, l_y\) are the mode indices determined by n_mode_x and n_mode_y.

• delta_omega_y_au (float, default: 0.0) – Frequency spacing along y-axis for cavity modes, in atomic units.

• n_mode_x (int, default: 1) – Number of cavity modes along x-axis.

• n_mode_y (int, default: 1) – Number of cavity modes along y-axis.

• abc_cutoff (float, default: 0.0) – Absorbing boundary condition cutoff for the molecular bath grid, in units of cavity length. The cutoff is applied to both x and y axes. If 0.0, no absorbing boundary condition is applied. If > 0.0, the grid points within the cutoff distance from the boundaries will be smoothly damped to suppress unphysical reflections of the EM field at the boundaries.

class maxwelllink.em_solvers.multimode_cavity.MoleculeMultiModeWrapper

Bases: MoleculeDummyWrapper

Wrapper that adapts a Molecule to MultiModeSimulation, handling units, sources, and IO.

__init__(molecule, dt_au)

Initialize the MultiMode molecule wrapper.

Parameters:

• molecule (Molecule) – The molecule to wrap.

• dt_au (float) – Time step in atomic units.

append_additional_data(time_au)

Store additional molecular data supplied by non-socket drivers.

Parameters:

time_au (float) – Current simulation time in atomic units.

calc_amp_vector()

Compute and return the current source amplitude vector from the molecule.

Returns:

Source amplitudes in atomic units.

Return type:

numpy.ndarray of float, shape (3,)

initialize_driver(assigned_id)

Initialize the wrapped molecule’s driver (non-socket mode).

Notes

Uses the molecule’s cached dt_au but changes its molecule_id from assigned_id.

Parameters:

assigned_id (int)

propagate(efield_vec3)

Propagate the wrapped molecule for one EM step.

Parameters:

efield_vec3 (array-like of float, shape (3,)) – Effective electric field vector in atomic units.

class maxwelllink.em_solvers.multimode_cavity.MultiModeSimulation

Bases: DummyEMSimulation

Mesoscale cavities coupled to MaxwellLink molecules.

All quantities are in atomic units.

__init__(dt_au=None, damping_au=0.0, molecules=None, hub=None, qc_initial=None, pc_initial=None, mu_initial=None, dmudt_initial=None, include_dse=True, molecule_half_step=False, shift_dipole_baseline=False, gauge='dipole', cavity_geometry=None, excited_mode_list=[], photon_pulse_drive=None, photon_pulse_axis='y', excited_grid_list=[], molecule_pulse_drive=None, molecule_pulse_axis='y', initializer=DummyInitializer(), thermostat=DummyThermostat())

Parameters:

• dt_au (float) – Simulation time step in atomic units.

• damping_au (float) – Damping constant \(\kappa\) (a.u.).

• molecules (iterable of Molecule, optional) – Molecules coupled to the cavity.

• hub (SocketHub, optional) – Socket hub shared by all socket-mode molecules.

• qc_initial (np.ndarray, default: None) – Initial cavity field coordinate (a.u.).

• pc_initial (np.ndarray, default: None) – Initial cavity field momentum (a.u.).

• mu_initial (np.ndarray, default: None) – Initial total molecular dipole vector (a.u.).

• dmudt_initial (np.ndarray, default: None) – Initial time derivative of the total molecular dipole vector (a.u.).

• include_dse (bool, default: True) – Include dipole self-energy term in the simulation.

• molecule_half_step (bool, default: True) – Whether to further evaluate molecular info for another half time step.

• shift_dipole_baseline (bool, default: False) – Whether to shift all dipole values using the initial dipole value, so initial dipole value is changed to zero. Setting this to True can facilitate simulating strong coupling systems with large permanent dipoles.

• gauge (str, default: "dipole") – Gauge choice for light-matter coupling: “dipole”.

• cavity_geometry (object, optional) – Cavity geometry object that defines the cavity mode structure and light-matter coupling. Must be an instance of a class that implements the necessary attributes and methods (e.g., omega_k, varepsilon_k, ftilde_k, etc.) as used in the equations of motion.

• excited_mode_list (list, optional) – List of excited cavity modes.

• photon_pulse_drive (float or callable, optional) – Constant photon pulse drive term or function photon_pulse_drive(t_au).

• photon_pulse_axis (str, default: "y") – pulse axis for the photon pulse.

• excited_grid_list (list, optional) – List of grid point indices that are excited by the molecule pulse. The excitation is applied by adding the molecule pulse drive to the effective electric field at these grid points.

• molecule_pulse_drive (float or callable, optional) – Constant molecule pulse drive or function molecule_pulse_drive(t_au) that determines the strength of the molecule pulse applied to the excited grid points. The callable may return a scalar, or vector-valued fields, or a per-grid array over excited_grid_list.

• molecule_pulse_axis (str, default: "y") – pulse axis for the molecule pulse.

• initializer (object, optional) – An object that provides methods to initialize cavity field coordinates and momenta, as well as molecular dipoles if needed. Must have methods position_initializer(omega, q) and momentum_initializer(p) that return initialized positions and momenta based on the cavity frequencies and/or other parameters. Two example initializers are provided in maxwelllink.tools.harmonic_oscillator_helper: DummyInitializer (returns zeros) and MaxwellBoltzmannInitializer (initializes based on Maxwell-Boltzmann distribution at a given temperature).

• thermostat (object, optional) – An object that provides a method to apply a thermostat to the cavity field momenta. Must have a method apply_kick(momentum) that takes the current momenta and returns the modified momenta after applying the thermostat kick. Two example thermostats are provided in maxwelllink.tools.harmonic_oscillator_helper: DummyThermostat (does nothing) and a simple LangevinThermostat that applies a frictional kick based on a specified temperature and damping constant.

run(until=None, steps=None, record_history=True, record_to_disk=False, disk_folder_address=None, npz_filename=None, h5_filename=None, record_max_steps=None, record_every_steps=1, record_list=None)

Run the simulation for a specified duration or number of steps.

Parameters:

• until (float, optional) – Total simulation time (a.u.). steps must be None.

• steps (int, optional) – Number of steps to execute. until must be None,

• record_history (bool, default: True) – Record time, field, velocity, drive, and molecular response histories.

• record_to_disk (bool, default: False) – Whether to save the history data to disk in HDF5 format. If False, the history data will be stored in memory.

• disk_folder_address (str, optional) – Folder path for saving history data when record_to_disk is True.

• npz_filename (str, optional) – Name of the .npz file to save the simulation results to when record_to_disk is True.

• h5_filename (str, optional) – Name of the .h5 file to save the simulation results to when record_to_disk is True.

• record_max_steps (int, optional) – Upper bound for the on-disk history length when record_to_disk is True. If None, the HDF5 datasets grow dynamically.

• record_every_steps (int, default: 1) – Number of steps to record data every record_every_steps steps.

• record_list (list of str, optional) – List of specific data fields to record. Possible values include “time”, “qc”, “pc”, “drive”, “energy”, “effective_efield”, “molecule_response”, “molecule_dipole”. If “all”, all fields will be recorded. If None, none will be recorded.

step(savedata=True, step_idx=None)

Advance the simulation by one time step.

Parameters:

• savedata (bool)

• step_idx (int | None)

storage_finalization()

Finalize storage for recording simulation history.

storage_initialization(steps=None, record_history=True, record_to_disk=False, disk_folder_address=None, npz_filename=None, h5_filename=None, record_max_steps=None, record_every_steps=1, record_list=None)

Initialize storage for recording simulation history.

Parameters:

• steps (int | None)

• record_history (bool)

• record_to_disk (bool)

• disk_folder_address (str | None)

• npz_filename (str | None)

• h5_filename (str | None)

• record_max_steps (int | None)

• record_every_steps (int)

• record_list (list | None)

class maxwelllink.em_solvers.multimode_cavity.MultiModeUnits

Bases: DummyEMUnits

EM units for multimode cavity simulations (1:1 to atomic units).

__init__()

efield_em_to_au(Emu_vec3)

Convert the electric field vector from EM units to atomic units (a.u.).

Parameters:

Emu_vec3 (array-like of float, shape (3,)) – Electric field vector in EM units.

Returns:

Electric field vector in atomic units.

Return type:

numpy.ndarray of float, shape (3,)

source_amp_au_to_em(amp_au_vec3)

Convert a source amplitude vector from atomic units (a.u.) to EM units.

Parameters:

amp_au_vec3 (array-like of float, shape (3,)) – Source amplitude vector in atomic units.

Returns:

Source amplitude vector in EM units.

Return type:

numpy.ndarray of float, shape (3,)

time_em_to_au(time_em)

Convert time from EM units to atomic units.

Parameters:

time_em (float) – Time in EM units.

Returns:

Time in atomic units.

Return type:

float

units_helper()

Return a human-readable description of these EM units.

Returns:

Description of the dummy EM unit system (1:1 conversion).

Return type:

str