Cavity HOOMD User Guide

Cavity HOOMD enables molecular dynamics simulations with optical cavity coupling using HOOMD-blue.

This package extends HOOMD-blue to simulate molecules interacting with optical cavity modes, enabling study of light-matter interactions, polariton chemistry, and cavity-modified molecular dynamics.

Quick Links

• New Users: Start with Getting Started

• Running Simulations: See Running Simulations

• Time-Varying Coupling: Learn about Time-Varying Coupling

• Data Management: Modern Data Management system

• Controllers: Advanced Controllers

• FDR Analysis: FDR Temperature measurements

• Theory Background: Read Introduction

• API Reference: Browse API Reference

• Installation Help: Installation

What Can You Do?

Core Capabilities:

• Simulate cavity-molecule coupling with time-dependent coupling strength

• Study strong coupling effects and polariton formation

• Analyze energy flow between molecular and photonic degrees of freedom

• Use advanced control systems for temperature and parameter management

• GPU-accelerated simulations for large systems

• Real-time data monitoring with HDF5-based output

• Comprehensive energy and temperature tracking

• Fluctuation-dissipation ratio analysis for non-equilibrium systems

Example Applications:

• Vibrational strong coupling in molecular ensembles

• Cavity-modified chemical dynamics

• Non-equilibrium switching experiments

• Polariton-mediated energy transfer

• Mode-selective chemistry under strong coupling

• Temperature control via coupling modulation

• Pump-probe dynamics simulations

Quick Example

Get started in minutes:

# Install
git clone https://github.com/muhammadhasyim/cav-hoomd.git
cd cav-hoomd
./build_install.sh

# Run your first cavity simulation
python examples/05_advanced_run.py --coupling 1e-3 --runtime 1000

With time-varying coupling:

# Coupling switch at t=10ps
python examples/05_advanced_run.py \
    --coupling 1e-3 \
    --switch-time 10.0 \
    --runtime 500

With advanced control:

from cavitymd import CavityMDSimulation
from cavitymd.controllers import PIDControl

# Setup simulation
sim = CavityMDSimulation(...)

# Add PID temperature controller
pid = PIDControl(
    simulation=sim,
    setpoint_K=100.0,
    auto_tune=True
)

sim.run()

That’s it! See Getting Started for detailed instructions.

What’s New

Recent Major Updates:

Data Management

• HDF5-based unified data output system

• 10-100x smaller file sizes

• Real-time monitoring with SWMR mode

• See Data Management

Controllers

• 7 controller types for different applications

• PID with auto-tuning

• Model Predictive Control (MPC)

• Adaptive and empirical controllers

• See Controllers

Coupling Variants

• 9 variant types for time-dependent protocols

• Step, periodic, decay, and adaptive variants

• Composite variant system

• See Time-Varying Coupling

FDR Analysis

• Complete workflow for effective temperature measurement

• Streaming algorithms for real-time analysis

• Mode-specific temperature decomposition

• See FDR Temperature

Performance

• Optimized GPU kernels

• Improved memory management

• Efficient autocorrelation algorithms

• See Performance

Documentation Structure

This documentation is organized into three main parts:

Part I: The Cavity HOOMD Application Layer

User-focused tutorials and guides for running simulations, from basic examples to advanced time-varying coupling experiments and data management.

Key Sections:

• Getting Started - First steps

• Running Simulations - Basic simulation workflow

• Advanced Simulations - Advanced features

• Time-Varying Coupling - Dynamic coupling protocols

• Data Management - HDF5 data system

• Analysis Tools - Analysis and tracking

Part II: Theory and Implementation

Mathematical foundations, equations of motion, energy conservation, and physical interpretation of cavity-molecule coupling.

Key Sections:

• Introduction - Theoretical foundations

• Cavity Forces - Force computation and Hamiltonian derivation

• Time-Varying Coupling - Time-dependent theory

• Thermostats - Thermostat implementations and bath models

• Observables - Observable calculations and correlation functions

• Integration Schemes - Numerical integration methods

• Energy Conservation - Energy conservation

• Strong Coupling - Strong coupling physics and off-resonance effects

Part III: Advanced Features and Analysis

Advanced controllers, FDR temperature measurement, molecular temperature decomposition, correlation analysis, and performance optimization.

Key Sections:

• Controllers - Control systems

• FDR Temperature - Effective temperature

• Molecular Temperatures - Temperature decomposition

• Correlation Analysis - Correlation functions

• Performance - Optimization strategies

---

Feature Highlights

Time-Varying Coupling

Complete variant system for any dynamic protocol:

from cavitymd.variants import (
    StepVariant,              # Sudden switching
    PeriodicVariant,          # Sinusoidal modulation
    SquareWaveVariant,        # Pulsed coupling
    ExponentialDecayVariant,  # Gradual changes
    AdaptiveSquareWaveVariant # Temperature-adaptive
)

# Example: Step switch
coupling = StepVariant(
    target_value=0.001,
    switch_time_ps=10.0,
    time_tracker=time_tracker
)

See Time-Varying Coupling for all 9 variant types.

Advanced Controllers

7 controller types for different objectives:

from cavitymd.controllers import (
    PIDControl,              # Classical PID
    DiffEqController,        # First-order dynamics
    SimpleSetpointController,# Direct control
    AdaptiveMPCController,   # Model predictive
    DualFeedbackController,  # Multi-mode
    EmpiricalController,     # Data-driven
    FeedbackController       # Base class
)

# Example: Auto-tuned PID
pid = PIDControl(
    simulation=sim,
    setpoint_K=100.0,
    auto_tune=True
)

See Controllers for detailed comparison.

Modern Data Management

HDF5-based system with live monitoring:

from cavitymd.data import ObservableWriter

# Single file for all observables
writer = ObservableWriter(
    output_file='sim_data.h5',
    enable_swmr=True  # Live read access
)

# 10-100x smaller than text files
# Hierarchical organization
# Real-time monitoring while running

See Data Management for full capabilities.

FDR Temperature Analysis

Effective temperature via fluctuation-dissipation:

from cavitymd import FDRWorkflow

# Complete FDR analysis
workflow = FDRWorkflow(
    observable='dipole',
    probe_frequency_cm=2000.0,
    equilibrium_duration_ps=200.0,
    response_duration_ps=200.0
)

results = workflow.run()
print(f"T_eff = {results['T_eff']:.2f} K")

See FDR Temperature for theory and examples.

GPU Acceleration

Optimized CUDA kernels for high performance:

import hoomd

# Automatically uses GPU when available
device = hoomd.device.GPU()
sim = hoomd.Simulation(device=device)

# All cavity forces run on GPU
cavity_force = CavityForce(...)

See Performance for optimization tips.

Help and Support

• GitHub Issues: https://github.com/muhammadhasyim/cav-hoomd/issues

• Discussions: https://github.com/muhammadhasyim/cav-hoomd/discussions

• Documentation: You’re reading it!

• Examples: Check examples/ directory for working scripts

Common Questions

Q: How do I start?

A: Follow Getting Started for installation and first simulation.

Q: How do I implement time-varying coupling?

A: See Time-Varying Coupling for all variant types.

Q: How do I control temperature?

A: See Controllers for 7 controller options.

Q: How do I analyze my data?

A: Use the Data Management HDF5 system and Analysis Tools.

Q: What about GPU performance?

A: See Performance for optimization strategies.

Citation

If you use Cavity HOOMD in your research, please cite:

@software{cavity_hoomd_2025,
  title={Cavity HOOMD: Molecular Dynamics with Optical Cavity Coupling},
  author={Development Team},
  year={2025},
  url={https://github.com/muhammadhasyim/cav-hoomd}
}

License

Cavity HOOMD is released under the BSD 3-Clause License. See License for details.

Indices and Tables

• Index

• Module Index

• Search Page