Lorentz-Bath driver
===================
.. warning::
This is a beta feature and may change in future versions.
The Lorentz-Bath driver implements a classical bright harmonic oscillator coupled
to a bath of classical dark oscillators. It is provided by
:class:`maxwelllink.mxl_drivers.python.models.LorentzBathModel` and ships with
**MaxwellLink** for reduced polaritonic-chemistry models where a collective
molecular bright mode exchanges energy with dark molecular modes.
.. note::
The Lorentz-Bath driver advances the bright coordinate :math:`q_B`, its
conjugate momentum :math:`p_B`, and bath coordinates :math:`q_j, p_j` generated
by the Hamiltonian
.. math::
H = \frac{1}{2}\left(p_B - \sum_j k_j q_j\right)^2
+ \frac{1}{2}\omega_0^2 q_B^2
- \mu_0 q_B\,\bigl(\widetilde{\mathbf{E}}(t)\cdot\mathbf{e}_i\bigr)
+ \sum_j\left(\frac{1}{2}\omega_j^2 q_j^2 + \frac{1}{2}p_j^2\right).
Here :math:`\mathbf{e}_i` denotes the selected dipole orientation, :math:`k_j`
are bright-dark coupling coefficients, and :math:`\omega_j` are bath-mode
frequencies. The emitted dipole current returned to Maxwell's equations is
evaluated by:
.. math::
\frac{d}{dt}\langle\boldsymbol{\mu}\rangle
= \mu_0\left(p_B - \sum_j k_j q_j\right)\mathbf{e}_i.
Requirements
------------
- No additional packages are required beyond **MaxwellLink**'s dependencies.
Usage
-----
Socket mode
^^^^^^^^^^^
.. code-block:: bash
mxl_driver --model lorentz_bath --port 31415 \
--param "omega=0.242, mu0=187, orientation=2, num_bath=101, \
bath_width=0.05, bath_form=lorentzian, bath_dephasing=0.002, \
checkpoint=false, restart=false"
Non-socket mode
^^^^^^^^^^^^^^^
.. code-block:: python
mxl.Molecule(
driver="lorentz_bath",
driver_kwargs={
"omega": 0.242,
"mu0": 187.0,
"orientation": 2,
"num_bath": 101,
"bath_width": 0.05,
"bath_form": "lorentzian",
"bath_dephasing": 0.002,
},
# ...
)
Parameters
----------
.. list-table::
:header-rows: 1
* - Name
- Description
* - ``omega``
- Bright oscillator frequency :math:`\omega_0` in atomic units. Default:
``2.4188843e-1``, corresponding to ``1.0`` in
`Meep `_ units when
``time_units_fs=0.1``.
* - ``mu0``
- Dipole-coordinate coupling prefactor :math:`\mu_0` in atomic units, so
that the instantaneous bright-mode dipole is :math:`\mu(t)=\mu_0 q_B(t)`;
scales the emitted source amplitude. Default: ``1.870819866e2``,
corresponding to ``0.1`` in `Meep `_
units when ``time_units_fs=0.1``.
* - ``orientation``
- Dipole orientation: ``0`` couples to ``E_x``, ``1`` to ``E_y``, ``2`` to
``E_z``. Default: ``2``.
* - ``num_bath``
- Number of bath oscillators used by the convenient bath builder. Must be
greater than ``1``. Used only when ``omega_bath`` and ``k_bath`` are not
both provided.
* - ``bath_width``
- Frequency width of the convenient bath distribution in atomic units. The
bath frequencies are placed uniformly from ``omega - 0.5*bath_width`` to
``omega + 0.5*bath_width``.
* - ``bath_form``
- Coupling-envelope form for the convenient bath builder. Supported values:
``uniform``, ``gaussian``, and ``lorentzian``.
* - ``bath_dephasing``
- Bright-to-dark dephasing scale in atomic units used by the convenient bath
builder to set the coupling coefficients :math:`k_j`. Default: ``0.0``.
* - ``bath_relaxation``
- Direct bath-momentum relaxation rate in atomic units. When positive,
bath momenta are damped by ``exp(-bath_relaxation*dt)`` each time step.
Default: ``0.0``.
* - ``omega_bath``
- Direct list of bath oscillator frequencies in atomic units. When supplied
together with ``k_bath``, this direct definition has priority over
``num_bath``/``bath_width``/``bath_form``.
* - ``k_bath``
- Direct list of bright-dark coupling coefficients in atomic units. Must
have the same length as ``omega_bath``.
* - ``p_initial``
- Initial bright-mode momentum :math:`p_B` in atomic units. Default:
``0.0``.
* - ``q_initial``
- Initial bright-mode position :math:`q_B` in atomic units. Default:
``0.0``.
* - ``p_bath_initial``
- Initial bath momenta as a list with the same length as the bath. Defaults
to zeros.
* - ``q_bath_initial``
- Initial bath positions as a list with the same length as the bath.
Defaults to zeros.
* - ``langevin_tau_au``
- Optional Langevin thermostat damping time in atomic units. The thermostat
is enabled during initialization when this value is provided and
``temperature_au > 0``. Default: ``None``.
* - ``initializer``
- Optional initializer. Supported value: ``maxwell_boltzmann``, which samples
bright and bath coordinates and momenta using ``temperature_au``.
* - ``temperature_au``
- Temperature in atomic units used by the Langevin thermostat and
``maxwell_boltzmann`` initializer. Default: ``0.0``.
* - ``random_seed``
- Random seed used by the initializer and thermostat. Default: ``114514``.
* - ``checkpoint``
- When ``True`` write ``lorentz_bath_checkpoint_id_.npz`` after each step.
Default: ``False``.
* - ``restart``
- When ``True`` resume from the latest checkpoint if present. Default:
``False``.
* - ``verbose``
- When ``True`` print field values and oscillator diagnostics each step.
Default: ``False``.
Returned data
-------------
- ``time_au`` - Simulation time in atomic units.
- ``energy_au`` - Total half-step Hamiltonian energy in atomic units.
- ``energy_lorentz_au`` - Bright oscillator contribution, including the
bright-bath momentum-shift terms, in atomic units.
- ``energy_bath_au`` - Bath oscillator energy in atomic units.
- ``mux_au``, ``muy_au``, ``muz_au`` - Half-step dipole vector components
(non-zero along the selected orientation) in atomic units.
- ``mux_m_au``, ``muy_m_au``, ``muz_m_au`` - Full-step bright-mode dipole vector
components in atomic units.
- ``p_au`` - Full-step bright-mode momentum :math:`p_B` in atomic units.
- ``q_au`` - Full-step bright-mode position :math:`q_B` in atomic units.
Notes
-----
- A bath definition is required. Provide either direct ``omega_bath`` and
``k_bath`` lists, or the convenient builder parameters ``num_bath``,
``bath_width``, and ``bath_form``.
- Direct ``omega_bath``/``k_bath`` settings have priority over the convenient
bath builder.
- The convenient bath builder currently places bath frequencies on an evenly
spaced grid and supports uniform, Gaussian, and Lorentzian coupling envelopes.
Use direct bath arrays for custom spectral densities.
- This driver is a reduced classical model intended for studying bright-mode
dephasing into dark molecular modes. For atomistic molecular dynamics, prefer
the **LAMMPS**, **DFTB+**, or **ASE** drivers.