Virtual Cavity RF Simulator

⚠️ Important Usage Guidelines

🐍 Python Version (Recommended for Scientific Applications)

Use for: Research, engineering calculations, precise simulations
Accuracy: Full numerical precision with validated LLRFLibsPy algorithms
Command: python advanced_cavity_gui.py

🌐 Web Version (Educational/Demo Purposes Only)

Use for: Educational demonstrations, basic visualization, parameter exploration
⚠️ Limitations: Approximate results only - not suitable for scientific calculations
Note: JavaScript implementation has inherent numerical precision limitations

🌐 Project Website: https://iuming.github.io/virtual-cavity-simulator/

🚀 Web Demo: Try the live web version - No installation required!

A comprehensive Radio Frequency (RF) cavity simulation platform with advanced graphical user interface for accelerator physics applications. Available both as a desktop Python application and a web-based simulator that runs in your browser.

🌟 Features

🎛️ Real-time Multi-Parameter Control

Amplitude Control: 0.0-2.0 range with precision sliders
Phase Control: -180° to +180° real-time phase adjustment
Frequency Offset: ±2000Hz detuning control
Beam Current: 0-0.02A beam loading simulation
Mode Switching: CW/Pulsed operation modes

📊 Multi-Curve Dynamic Visualization

Cavity Voltage: Real-time magnitude and phase monitoring
Reflected Power: Forward/reflected power analysis
Detuning: Frequency offset tracking
Mechanical Modes: 5-mode microphonics simulation
Response Curves: Parameter sweep visualization

🔍 Advanced Data Analysis

Data Recording: Start/stop recording with timestamp
Export Formats: CSV and JSON data export
Historical Playback: Data replay and analysis
Large Dataset: 10,000+ data points buffer

🧪 Parameter Scanning

Multi-Parameter: Amplitude/Phase/Frequency/Current scanning
Custom Ranges: User-defined scan parameters
Response Analysis: 20-point automatic response curves
Progress Tracking: Real-time scan progress display

🚀 Quick Start

🌐 Web Version (Recommended for Quick Testing)

No installation required! Try the simulator directly in your browser:

👉 Launch Web Simulator

Features:

Runs on any modern browser (desktop/mobile)
Real-time RF cavity simulation
Interactive parameter control
Data export (CSV/JSON)
Responsive design

🖥️ Desktop Version (Full Features)

For advanced research and maximum accuracy:

Prerequisites

# Python 3.7 or higher
python --version

# Required packages
pip install numpy matplotlib tkinter

Installation

# Clone the repository
git clone https://github.com/iuming/virtual-cavity-simulator.git
cd virtual-cavity-simulator

# Install dependencies
pip install -r requirements.txt

# Install LLRFLibsPy (required)
# Follow LLRFLibsPy installation instructions

Launch the Simulator

# Start the GUI application
python launch_gui.py

# Or run standalone simulation
python sim_cavity_standalone.py

📖 Usage Guide

Basic Operation

Start Simulation: Click "Start" to begin real-time simulation
Parameter Control: Use sliders to adjust RF parameters
Data Recording: Click "Start Recording" to save data
Parameter Scanning: Select parameter and range for automatic scanning
Export Data: Save results in CSV or JSON format

Advanced Features

Resonance Analysis: Set frequency offset to -460Hz for resonance observation
Transient Response: Switch to pulsed mode for transient analysis
Linear Region: Scan amplitude parameters to analyze linear operation
Beam Loading: Adjust beam current to observe loading effects

🏗️ Technical Architecture

Core Components

RF Source Module: Signal generation and modulation
Cavity Dynamics: State-space cavity model with mechanical coupling
Visualization Engine: Real-time multi-plot display system
Data Management: Recording, storage, and export functionality

Simulation Parameters

Time Resolution: 1 μs time steps
Cavity Frequency: 1.3 GHz (configurable)
Quality Factor: 3×10⁶ (loaded)
Mechanical Modes: 5 modes (280, 341, 460, 487, 618 Hz)
Beam Parameters: Variable current 0-20 mA

📁 Project Structure

virtual-cavity-simulator/
├── advanced_cavity_gui.py     # Main GUI application
├── sim_cavity_standalone.py   # Standalone simulation
├── launch_gui.py              # Application launcher
├── requirements.txt           # Python dependencies
├── README.md                  # This file
├── LICENSE                    # MIT license
├── docs/                      # Documentation
│   ├── installation.md        # Installation guide
│   ├── user_guide.md          # User manual
│   └── api_reference.md       # API documentation
├── examples/                  # Example scripts
│   ├── basic_simulation.py    # Basic usage example
│   └── parameter_sweep.py     # Parameter scanning example
└── tests/                     # Unit tests
    ├── test_simulation.py     # Simulation tests
    └── test_gui.py            # GUI tests

🔬 Scientific Applications

Accelerator Physics

Cavity Design: RF cavity parameter optimization
Control System: LLRF control algorithm development
Microphonics: Mechanical vibration analysis
Beam Loading: Beam-cavity interaction studies

Research Areas

Superconducting Cavities: SRF cavity dynamics
Linear Accelerators: LINAC RF system design
Free Electron Lasers: FEL RF control systems
Storage Rings: Synchrotron RF cavity analysis

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

# Fork and clone the repository
git clone https://github.com/iuming/virtual-cavity-simulator.git

# Create a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
python -m pytest tests/

📊 Performance

Real-time Performance: 1000+ simulations/second
Memory Usage: <100MB for typical operations
Data Capacity: 10,000+ data points with smooth visualization
Platform Support: Windows, Linux, macOS

📚 Documentation

🐛 Known Issues

Windows Installation: Some dependencies may require Microsoft C++ Build Tools
Matrix Conditioning: Scipy warnings for ill-conditioned matrices (non-critical)

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👨‍💻 Author

Ming Liu

Email: mliu@ihep.ac.cn
Institution: Institute of High Energy Physics, Chinese Academy of Sciences
ORCID: 0000-0001-6239-1180

🙏 Acknowledgments

LLRFLibsPy Team: For the excellent RF simulation framework
IHEP: For supporting this research and development
Community: For feedback and contributions

📈 Citation

If you use this software in your research, please cite:

@software{liu2025virtualcavity,
  title={Virtual Cavity RF Simulator},
  author={Liu, Ming},
  year={2025},
  institution={Institute of High Energy Physics, Chinese Academy of Sciences},
  url={https://github.com/iuming/virtual-cavity-simulator}
}

🔗 Related Projects

LLRFLibsPy - Low-Level RF Library for Python
pythonSoftIOC - Python Soft IOC Framework

⭐ Star this repository if you find it useful!

📧 Contact: For questions or support, please email mliu@ihep.ac.cn

Name		Name	Last commit message	Last commit date
Latest commit History 22 Commits
.github/workflows		.github/workflows
docs		docs
examples		examples
tests		tests
web		web
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
advanced_cavity_gui.py		advanced_cavity_gui.py
launch_gui.py		launch_gui.py
requirements-dev.txt		requirements-dev.txt
requirements.txt		requirements.txt
setup.py		setup.py
sim_cavity_standalone.py		sim_cavity_standalone.py

License

iuming/virtual-cavity-simulator

Folders and files

Latest commit

History

Repository files navigation