maxwelllink.em_solvers.single_mode_cavity module

Single-mode cavity electrodynamics for MaxwellLink.

This module defines a lightweight cavity simulator that treats the EM field as one damped harmonic oscillator 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.single_mode_cavity.MoleculeSingleModeWrapper

Bases: MoleculeDummyWrapper

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

__init__(molecule, dt_au)

Initialize the SingleMode molecule wrapper.

Parameters:

• molecule (Molecule) – The molecule to wrap.

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

• axis (int or str) – Axis of the molecule to be coupled to the cavity mode. Accepted values: 0, 1, 2 or "x", "y", "z" (case-insensitive).

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.single_mode_cavity.SingleModeSimulation

Bases: DummyEMSimulation

Damped harmonic oscillator 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} \omega_{\rm c}^2 (q_{\rm c} + \frac{\varepsilon}{\omega_{\rm c}^2} \sum_i \mu_i)^2\]

The cavity mode (classical harmonic oscillator) obeys

\[\ddot{q}_{\rm c} = -\omega_c^{2}\, q_{\rm c} \; - \; \varepsilon \sum_i \mu_i \;-\; \gamma_{\rm c} \, p_{\rm c} \;+\; D(t),\]

where the effective electric field of this cavity mode is

\[E(t) = -\varepsilon q_{\rm c}(t) - \frac{\varepsilon^2}{\omega_{\rm c}^2} \sum_i \mu_i(t),\]

where \(\varepsilon\) is coupling_strength and the sum runs over the selected molecular axis of all molecules. The second term in the electric field accounts for the dipole self-energy term if enabled.

Under the velocity gauge, \(d\mu/dt\) is coupled to cavity momentum instead of \(\mu\) to cavity position. The total Hamiltonian is

\[H = H_{mol} + \frac{1}{2} (p_{\rm c} - \frac{\varepsilon}{\omega_{\rm c}} \sum_i \mu_i)^2 + \frac{1}{2} \omega_{\rm c}^2 q_{\rm c}^2\]

The cavity mode (classical harmonic oscillator) obeys

\[\ddot{q}_{\rm c} = -\omega_c^{2}\, q_{\rm c} \; - \; \frac{\varepsilon}{\omega_{\rm c}} \sum_i \frac{d\mu_i}{dt} \;-\; \gamma_{\rm c} \, p_{\rm c} \;+\; D(t),\]

where the effective electric field of this cavity mode is

\[E(t) = \frac{\varepsilon}{\omega_{\rm c}} \dot{q}_{\rm c}(t) = \frac{\varepsilon}{\omega_{\rm c}} (p_c - \frac{\varepsilon}{\omega_{\rm c}} \sum_i \mu_i).\]

All quantities are in atomic units.

__init__(dt_au, frequency_au, damping_au, molecules=None, drive=None, coupling_strength=1.0, coupling_axis='xy', hub=None, qc_initial=None, pc_initial=None, mu_initial=None, dmudt_initial=None, record_history=True, include_dse=False, molecule_half_step=False, shift_dipole_baseline=False, gauge='dipole')

Parameters:

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

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

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

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

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

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

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

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

• qc_initial (list, default: [0.0, 0.0, 0.0]) – Initial cavity field coordinate (a.u.).

• pc_initial (list, default: [0.0, 0.0, 0.0]) – Initial cavity field momentum (a.u.).

• mu_initial (list, default: [0.0, 0.0, 0.0]) – Initial total molecular dipole vector (a.u.).

• dmudt_initial (list, default: [0.0, 0.0, 0.0]) – Initial time derivative of the total molecular dipole vector (a.u.).

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

• 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” or “velocity”. Using velocity gauge will couple to dmu/dt to cavity momentum instead of mu to the cavity position.

run(until=None, steps=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.

step()

Advance the simulation by one time step.

class maxwelllink.em_solvers.single_mode_cavity.SingleModeUnits

Bases: DummyEMUnits

EM units for single-mode 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