rheoQCM 0.1.1

QCM-D data analysis software with rheological modeling

RheoQCM - QCM Data Analysis Software

RheoQCM is a Python package for QCM-D (Quartz Crystal Microbalance with Dissipation) rheological analysis. It features a modern JAX-powered computational core for high-performance modeling and a PyQt6-based GUI for visualization and data exploration.

Screenshot of the User Interface

Features

• High-performance modeling with JAX (GPU-accelerated when available)
• Import and analyze external QCM-D datasets (.xlsx, .mat, .h5)
• Multilayer thin-film analysis using the Small Load Approximation (SLA)
• Bayesian parameter estimation with MCMC (NumPyro backend)
• Uncertainty quantification via autodiff-based covariance propagation
• Cross-platform (Linux/macOS/Windows)

Requirements

• Python 3.12+
• JAX 0.8.0+ with jaxlib 0.8.0+
• PyQt6 (for GUI)
• NumPy 2.0+

Installation

From PyPI (Recommended)

pip install rheoQCM

From Source

git clone https://github.com/imewei/RheoQCM.git
cd RheoQCM
pip install -e .

GPU Acceleration (Linux + NVIDIA)

For 20-100x speedup on large datasets:

# Auto-detect system CUDA version and install matching JAX
make install-jax-gpu

# Or explicitly choose CUDA version:
make install-jax-gpu-cuda13  # CUDA 13.x + SM >= 7.5
make install-jax-gpu-cuda12  # CUDA 12.x + SM >= 5.2

Prerequisites:

• NVIDIA GPU (Maxwell or newer, SM >= 5.2)
• System CUDA 12.x or 13.x installed (nvcc in PATH)

GPU Compatibility Table

GPU Generation	Example GPUs	SM Version	CUDA 13	CUDA 12
Ada Lovelace	RTX 40xx, L40	8.9	Yes	Yes
Ampere	RTX 30xx, A100	8.x	Yes	Yes
Turing	RTX 20xx, T4	7.5	Yes	Yes
Volta	V100, Titan V	7.0	No	Yes
Pascal	GTX 10xx, P100	6.x	No	Yes
Maxwell	GTX 9xx	5.x	No	Yes

Quick Start

Using the GUI

python -m rheoQCM.main

Scripting with the Core API

from rheoQCM.core import QCMModel, configure_jax

configure_jax()  # Enable float64 precision

# Create model and load experimental data
model = QCMModel(f1=5e6, refh=3)
model.load_delfstars({3: -1000+100j, 5: -1700+180j, 7: -2500+280j})

# Solve for mechanical properties
result = model.solve_properties(nh=[3, 5, 3])
print(f"drho = {result.drho:.3e} kg/m^2")
print(f"phi = {result.phi:.4f} rad")
print(f"|G*|rho = {result.grho_refh:.3e} Pa·kg/m^3")

Batch Processing with GPU Acceleration

import jax.numpy as jnp
from rheoQCM.core import batch_analyze_vmap

# Process many data points in parallel
delfstars = jnp.array([
    [-1000+100j, -1700+180j, -2500+280j],
    [-1100+110j, -1800+190j, -2600+290j],
    # ... thousands more rows
])
results = batch_analyze_vmap(delfstars, harmonics=[3, 5, 7], f1=5e6, refh=3)

Importing QCM-D Data

1. Export from instrument as .xlsx with columns: t(s), delf1, delg1, delf3, delg3, ...
2. In GUI: File > Import QCM-D data
3. Set base frequency in Settings > Hardware > Crystal > Base Frequency
4. Analyze and export results

Documentation

• Full Documentation - API reference, tutorials, and guides
• Migration Guide - Upgrading from QCMFuncs to rheoQCM.core
• QCM Notes - Background theory and references

Project Structure

src/
  rheoQCM/           # Main package
    core/            # JAX-accelerated computational core
      physics.py     # Layer 1: Pure physics functions
      multilayer.py  # Layer 1: Multilayer calculations
      model.py       # Layer 2: State management and solvers
      analysis.py    # Layer 3: Analysis interface
      bayesian.py    # Bayesian MCMC fitting
      uncertainty.py # Uncertainty propagation
    gui/             # PyQt6 GUI components
    io/              # I/O handlers (HDF5, Excel, JSON)
    modules/         # Application modules
    services/        # Service layer
tests/               # Test suite
docs/                # Sphinx documentation

Citation

Please cite as:

@software{rheoqcm,
  author = {Wang, Qifeng and Yang, Megan and Shull, Kenneth R. and Chen, Wei},
  title = {RheoQCM: QCM Data Analysis Software},
  year = {2025},
  publisher = {GitHub},
  url = {https://github.com/shullgroup/rheoQCM},
  doi = {10.5281/zenodo.2486039}
}

Authors

• Qifeng Wang - Primary developer
• Megan Yang - Developer
• Kenneth R. Shull - Project PI

Fork Maintainer

• Wei Chen ([e-mail]) - Contributor and maintainer of this fork

Related Projects

• MATLAB QCM Data Acquisition - Original MATLAB version
• QCM-D Analysis GUI - MATLAB analysis by Kazi Sadman

License

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

Acknowledgments

• Josh Yeh - Original MATLAB implementation
• Diethelm Johannsmann - QCM theory
• Lauren Sturdy, Ivan Makarov - Technical contributions