QuTiP driver¶

The QuTiP driver embeds MaxwellLink in the rich modelling ecosystem provided by QuTiP. It can run preset TLS models or load user-defined Hamiltonians, collapse operators, and initial states from an external Python module. This Python driver is implemented in maxwelllink.mxl_drivers.python.models.QuTiPModel.

Note

The QuTiP driver advances the density matrix according to

\[\frac{d}{dt}\hat{\rho}(t) = -\frac{i}{\hbar}\left[\hat{H} - \widetilde{\mathbf{E}}(t)\cdot \hat{\boldsymbol{\mu}}, \hat{\rho}(t)\right] - \mathcal{L}\bigl[\hat{\rho}(t)\bigr],\]

where the Hamiltonian, dipole operators, and optional Lindblad super-operators are supplied by the user. The emitted dipole current is returned via

\[\frac{d}{dt}\langle \hat{\boldsymbol{\mu}} \rangle = \mathrm{Tr}\!\left(\frac{d}{dt}\hat{\rho}(t)\,\hat{\boldsymbol{\mu}}\right),\]

providing a consistent source term for Maxwell’s equations.

Requirements¶

qutip (install via conda install -c conda-forge qutip).
Any custom module referenced through module=... must be importable on the driver side.

Usage¶

Socket mode¶

mxl_driver --model qutip --port 31415 \
  --param "preset=tls, fd_dmudt=false, \
           preset_kwargs=omega=0.242,mu12=187,orientation=2,pe_initial=1e-3, \
           gamma_relax=0.0, gamma_dephase=0.0"

Non-socket mode¶

mxl.Molecule(
    driver="qutip",
    driver_kwargs={
        "preset": "tls",
        "preset_kwargs":
            "omega=0.242,mu12=187,orientation=2,pe_initial=1e-3,\
             gamma_relax=0.0,gamma_dephase=0.0",
        "verbose": True,
    },
    # ...
)

Parameters¶

Name	Description
`preset`	`tls` for the built-in two-level system or `custom` to load a user module. Default: `tls`.
`preset_kwargs`	Comma-separated overrides for the TLS preset (same parameters as the TLS driver, plus Lindblad rates `gamma_relax` and `gamma_dephase`). TLS keys can also be given as top-level `--param` tokens and are merged here. Default: `""`.
`module`	(`preset=custom`) Path to a Python file that defines `build_model(**kwargs)` returning a dict with `H0`, `mu_ops`, optional `c_ops`, and an initial density matrix `rho0`. Default: `None`.
`kwargs`	Parameters forwarded to `build_model` when using the custom preset. Default: `""`.
`fd_dmudt`	When `True` force a finite-difference evaluation of \(\mathrm{d}\mu/\mathrm{d}t\); when `False` an analytical expression is used when available. Default: `False`.
`verbose`	When `True` the driver prints initialization details and time-step diagnostics. Default: `False`.
`checkpoint`	When `True` the driver saves intermediate results to disk for later analysis. Default: `False`.
`restart`	When `True` the driver attempts to load checkpointed data on startup. Default: `False`.

Reference custom module¶

The TLS regression test tests/test_qutip/test_meep_2d_socket_qutip_tls_relaxation.py launches the driver in preset=custom mode. The helper tests/test_qutip/build_tls.py defines:

def build_model(**kwargs):
    return {
        "H0": qutip.Qobj(...),            # bare Hamiltonian
        "mu_ops": {"x": mux, "y": muy, "z": muz},
        "c_ops": [ ... ],                 # optional collapse operators
        "rho0": qutip.Qobj(...),          # initial density matrix or ket
    }

Any unused dipole components can be set to None. Collapse operators are optional.

Returned data¶

The driver pushes several parameters back to the EM process and can be retrieved from Molecule.additional_data_history (see tests/test_qutip/test_meep_2d_socket_qutip_tls_relaxation.py):

time_au – Simulation time in atomic units.
energy_au – Instantaneous expectation value of the system Hamiltonian.
mux_au, muy_au, muz_au – Dipole expectation values in atomic units.
rho_diag – Density matrix diagonal elements (populations) as a list.
Pg / Pe – Ground- and excited-state populations when the Hilbert space dimension is two.
Pge_real / Pge_imag – Real and imaginary parts of the TLS coherence when the Hilbert space dimension is two.