maxwelllink 0.5.0

MaxwellLink is a free and open-source framework for self-consistent light–matter simulations. It connects electromagnetic solvers, such as MEEP FDTD or the built-in normal-mode cavity and laser driven dynamics, to a wide range of molecular drivers, from multilevel open quantum systems to (nonadiabatic) first-principles molecular dynamics.

This code supports both exploratory demonstrations and production-scale calculations. In particular, its socket-based architecture allows large-scale self-consistent light–matter simulations to run efficiently across multiple HPC nodes.

Key Features

• Embracing state-of-the-art ecosystems in both computational electrodynamics and quantum chemistry, extending the boundary of light-matter simulations.
• Unified Python interfaces for socket-connected and embedded molecular drivers in light-matter simulations.
• EM dynamics from simple to complex systems.
• Heterogeneous molecular theories in one simulation.
• Extensible code structure to add custom EM solvers or molecular drivers with minimal effort.
• Embedded AI Agent Skills to allow users to chat within, e.g., Visual Code IDE + Codex, to directly generate desired input files and even run jobs on both local machines and HPC systems.

Supported light-matter simulation schemes

The most appealing feature of MaxwellLink is that it enables the self-consistent coupling of one EM solver plus N different molecular drivers concurrently.

The socket communication technique further allows distributed light-matter simulations on different machines and HPC nodes, i.e., both the EM solver and molecular drivers can have their own MPI parallel processes.

As of today, the following EM solvers and molecular drivers are supported.

Supported EM solvers

• Full-feature MEEP FDTD in 1D, 2D, 3D, and cylindrical coordinates (3D simulations at 2D cost),
• Single-mode cavity,
• Multimode Fabry-Perot cavity, and
• Arbitrary laser driven dynamics.

Supported molecular drivers

• Two-level systems and simple harmonic oscillators,
• QuTiP model Hamiltonians,
• In-house RT-TDDFT/Ehrenfest dynamics using Psi4 integrals,
• ASE classical dynamics,
• Direct socket connection to modified LAMMPS for classical MD via fix mxl,
• (beta version) Lorentz-Bath model for studying energy transfer between polaritons and dark modes,
• (beta version) Direct socket connection to modified DFTB+ for tight-binding BOMD/real-time Ehrenfest dynamics.
• (beta version) Direct socket connection to modified CP2K for real-time TDDFT/Ehrenfest dynamcis in both non-periodic and periodic systems.

Quick Start

Create a fresh conda environment and install using pip:

pip install maxwelllink

Optional drivers (MEEP FDTD, QuTiP, Psi4, ASE, LAMMPS) can be added by following the instructions in the documentation.

Documentation

Visit the documentation for installation details, tutorials, API reference, and guidelines on extending MaxwellLink.

Tutorials

The jupyter notebook tutorials are located at tutorials/. Users may also view the tutorials rendered at the documentation website.

Running simulations with AI Agents

Inspired by the recently developed FermiLink agent framework, MaxwellLink now provides an elegant method for integrating with AI agents. All we need is to type in mxl init in a working directory:

mkdir myproject
cd myproject/
mxl init

Then we can interact with any local AI agent (Claude Code, OpenAI Codex, Gemini CLI, or their desktop apps, VS Code IDE extensions, etc) for autonomous light-matter simulations by simple natural language prompts.

mxl init will set up the package knowledge base (source code tree + agent skills layer) in your working directory for agent reasoning. After the simulation, we can simply clean up the package knowledge base by:

mxl clean

If your machine supports SLURM job management (such as HPCs), run the following command to set up the HPC environment, so the agent can automatically use the correct SLURM environments for large-scale HPC simulations.

mxl hpc

Citation

If you find MaxwellLink helpful for your research, please cite the following reference:

• X Ji †, AF Bocanegra Vargas †, G Meng, and TE Li. MaxwellLink: A Unified Framework for Self-Consistent Light-Matter Simulations. J. Chem. Theory Comput. 22, 2725–2738 (2026). [data] [arXiv:2512.06173]

Publications using MaxwellLink

• X Ji, and TE Li. Nonlinear Freezing of Vibrational Polariton Transport via Mesoscale Simulations. Nano Lett. acs.nanolett.6c03367 (2026). [data]

• Meng, G.; Li, T. E. Molecular Electrodynamic Relaxation in Dielectric and Plasmonic Cavities Submitted (2026).