Introduction

MaxwellLink provides a flexible software bridge between electromagnetic (EM) solvers, such as finite-difference time-domain (FDTD) approach, and quantum or classical molecular dynamics engines. The toolkit originated in the TEL Research Group at University of Delaware and is designed for self-consistent light-matter simulations in which both the EM and molecular subsystems evolve using state-of-the-art computational methods.

MaxwellLink can be used for both demonstration and production purposes. With a single laptop, we can use MaxwellLink to prototype light-matter dynamics involving model systems or first-principles quantum dynamics. On high-performance computing clusters, MaxwellLink can couple a parallel FDTD solver with hundreds of molecular drivers running across networked nodes using a TCP socket interface.

MaxwellLink workflow diagram

Key capabilities

  • Simplified and unified Python API for self-consistent light-matter simulations.

  • Couple an EM solver (such as Meep FDTD or a single-mode cavity) to one or many molecular drivers running in the same process or across networked nodes via TCP sockets.

  • Mix heterogeneous molecular theories within a single EM simulation, ranging from two-level systems (TLSs), QuTiP model Hamiltonians, to Psi4-based RT-TDDFT, Ehrenfest dynamics, and ASE- and LAMMPS-powered molecular mechanics.

  • Tolerate driver pauses or restarts — the SocketHub automatically waits for reconnections before resuming a simulation step.

  • Operate under MPI: only the master rank in the EM simulation speaks to the drivers while field data and molecular response are broadcast to worker ranks.

  • Flexible to extend: users can implement custom molecular drivers or EM solvers by writing a few wrapper functions; see Contributing for details.

Included EM solvers

  • Meep FDTD – a popular (industry-standard) open-source FDTD package with a user-friendly Python interface maintained by MIT.

  • Single-mode cavity – a simple 1D cavity mode solver with support for damping and external driving fields, useful for prototyping, debugging, and simplified quantum optics and polaritonics calculations.

  • Laser driven dynamics – a driver that applies arbitrary user-defined classical electric fields without back-action from the molecular system, useful for pump-probe and strong-field simulations.

Included molecular drivers

  • Model systems – a lightweight TLS driver and a QuTiP interface for custom Hamiltonians with optional Lindblad terms.

  • First-principles nonadiabatic quantum dynamics – RT-TDDFT and RT-TDDFT-Ehrenfest drivers implemented using Psi4.

  • Classical or first-principles molecular mechanics – ASE drivers that wrap any ASE calculator (including Psi4, ORCA, DFTB+) and a LAMMPS plugin using fix mxl.

Learning path

  1. Installation walks through the recommended conda environment and optional driver dependencies.

  2. Usage Guide shows how to launch a Meep simulation, connect a TLS driver, and inspect the returned molecular data.

  3. Tutorials provides hands-on tutorials regarding setting up and using MaxwellLink with different EM solvers and drivers.

  4. Architecture explains the socket protocol, molecular wrappers, and how MaxwellLink keeps the EM solver and drivers synchronized.

  5. EM Solvers documents all shipped EM solvers, their required parameters, and expected outputs.

  6. Drivers documents all shipped molecular drivers, their required parameters, and expected outputs.

  7. Contributing guides users on how to implement custom EM solvers and molecular drivers to extend the MaxwellLink framework.

  8. maxwelllink lists the complete API reference for all MaxwellLink classes and functions.