Alprotein makes complex excitonic calculations accessible through an intuitive graphical interface, while providing the full power of a Python API for advanced users and automation.
Unlike traditional command-line only tools, Alprotein features a modern GUI workbench that guides you through the entire workflow—from loading PDB structures to visualizing optical spectra—without writing a single line of code. For researchers who need automation or custom workflows, the same functionality is available through a clean Python API.
Interactive GUI for calculating excitonic properties and optical spectra
- Point-and-click workflow - No programming required for standard calculations
- Interactive visualization - Real-time 3D structure viewing and spectra plotting
- Guided parameter selection - Built-in tooltips and validation
- Live feedback - Watch calculations progress with detailed status updates
- Export-ready results - One-click saving of Hamiltonians, spectra, and visualizations
- Full Python API for automation and batch processing
- Integrate into existing computational pipelines
- Custom workflows and analysis scripts
- Reproducible, version-controlled calculations
- Load protein structures from PDB files
- Identify and configure pigments (Chlorophyll A, B, Bacteriochlorophyll, etc.)
- Compute site energies using CDC method
- Calculate pigment-pigment couplings (TrEsp or dipole approximation)
- Build and diagonalize excitonic Hamiltonians
- Generate absorption and fluorescence spectra with vibronic coupling
- Define and analyze excitonic domains
Most computational tools for excitonic calculations require extensive programming knowledge and command-line expertise. Alprotein breaks down this barrier with a graphical interface that makes sophisticated quantum mechanical calculations accessible to all researchers—from experimental biophysicists to computational experts.
The GUI is not an afterthought—it's a core feature designed from the ground up to handle the full complexity of excitonic calculations while remaining intuitive and user-friendly.
At the same time, power users get a clean, well-documented Python API for automation, batch processing, and integration into existing pipelines. You're not limited to one approach—use what fits your workflow.
git clone https://github.com/melrefaiy2018/Alprotein.git
cd Alprotein
conda create -n alprotein python=3.11
conda activate alprotein
pip install -e .After installation, start the interactive workbench:
python tools/launch_workbench.py That's it! The GUI will open and guide you through the entire workflow.
- Python 3.8 or newer
- NumPy, SciPy, pandas
- BioPython
- matplotlib
- PyQt5 or PySide6 (for GUI)
Launch the interactive workbench:
python -m Alprotein.workbench
# Or if you have the tools directory:
# python tools/launch_workbench.pyThe GUI provides a step-by-step workflow:
- Load Structure - Browse and load your PDB file
- Configure Pigments - Select pigment types and parameters from dropdown menus
- Compute Properties - Click to calculate site energies and couplings
- Build Hamiltonian - Set dielectric constants and construct the excitonic Hamiltonian
- Calculate Spectra - Configure temperature, disorder, and generate absorption/fluorescence spectra
- Visualize & Export - Interactive plots and one-click export of all results
No coding required - the GUI handles all the complexity while giving you full control over parameters.
For scripting, batch processing, or integration into computational pipelines, here's a complete programmatic workflow:
import numpy as np
import matplotlib.pyplot as plt
from Alprotein import (
ProteinStructure,
PigmentSystem,
ChlorophyllA,
HamiltonianCalculator,
SpectraCalculator
)
# ============================================================================
# STEP 1: Load Protein Structure
# ============================================================================
print("[1] Loading protein structure...")
protein = ProteinStructure.from_file("structure.pdb", name="MyComplex")
print(f" ✓ Loaded structure with {len(protein.atoms)} atoms")
# ============================================================================
# STEP 2: Build Pigment System
# ============================================================================
print("\n[2] Building pigment system...")
pigment_system = PigmentSystem(protein)
# Add chlorophyll A pigments from the structure
pigment_system.add_pigments_by_residue(
resname="CLA", # Residue name in PDB file
pigment_class=ChlorophyllA, # Pigment type class
tresp_dict_name="CLA_IPPC", # Transition charge parameter set
cdc_dict_name="CLA", # CDC parameter set
)
print(f" ✓ Identified {len(pigment_system.pigments)} pigments")
# Compute site energies using CDC method
site_energies = pigment_system.compute_site_energies()
print(f" ✓ Computed site energies (mean: {np.mean(site_energies):.1f} cm⁻¹)")
# Compute pigment-pigment couplings using TrEsp method
couplings = pigment_system.compute_couplings(method="TrEsp")
print(f" ✓ Computed couplings (max: {np.max(np.abs(couplings)):.1f} cm⁻¹)")
# ============================================================================
# STEP 3: Construct Hamiltonian
# ============================================================================
print("\n[3] Constructing Hamiltonian...")
hamiltonian_calculator = HamiltonianCalculator(
pigment_system,
dielectric_cdc=2.0, # Dielectric constant for CDC calculation
dielectric_tresp=1.0, # Dielectric constant for TrEsp coupling
f_val=0.72, # Oscillator strength
E_0a=14900.0, # Reference energy for Qy transition (cm⁻¹)
E_0b=15674.0 # Reference energy for Qx transition (cm⁻¹)
)
# Build the Hamiltonian matrix
hamiltonian_df = hamiltonian_calculator.construct_hamiltonian(
params={'coupling_calc': 'tresp'} # Use TrEsp for couplings
)
hamiltonian = hamiltonian_df.values
print(f" ✓ Hamiltonian constructed ({hamiltonian.shape[0]}×{hamiltonian.shape[1]})")
# ============================================================================
# STEP 4: Define Excitonic Domains
# ============================================================================
print("\n[4] Defining excitonic domains...")
domain_cutoff = 20.0 # Coupling threshold in cm⁻¹
domains_dict = hamiltonian_calculator.build_domains(
cutoff=domain_cutoff,
hamiltonian=hamiltonian_df,
)
print(f" ✓ Found {len(domains_dict)} domains")
# ============================================================================
# STEP 5: Calculate Optical Spectra
# ============================================================================
print("\n[5] Calculating optical spectra...")
# Set calculation parameters
temperature = 300.0 # Temperature in Kelvin
disorder_fwhm = 130.0 # Inhomogeneous broadening FWHM (cm⁻¹)
n_ensemble = 300 # Number of disorder realizations
dt = 0.1 # Time step in femtoseconds
t_max = 2000.0 # Maximum time in femtoseconds
print(f" Parameters:")
print(f" - Temperature: {temperature} K")
print(f" - Disorder FWHM: {disorder_fwhm} cm⁻¹")
print(f" - Ensemble size: {n_ensemble}")
print(f" - Time range: 0-{t_max} fs (step: {dt} fs)")
# Initialize spectra calculator
spectra_calc = SpectraCalculator(
temperature=temperature,
disorder_sigma=disorder_fwhm, # Converted to sigma internally
n_ensemble=n_ensemble,
dt=dt,
t_max=t_max
)
print(f" ✓ SpectraCalculator initialized")
print(f" - Reorganization energy: {spectra_calc.reorganization_energy:.1f} cm⁻¹")
# Calculate absorption and fluorescence spectra
wavelengths_abs, absorption, wavelengths_fl, fluorescence = spectra_calc.calculate_spectrum(
hamiltonian=hamiltonian,
domains=domains_dict,
pigment_system=pigment_system,
include_vibronic=True, # Include 0-1 vibronic transitions
use_ensemble=True # Use ensemble averaging
)
print(f" ✓ Spectra calculated")
# ============================================================================
# STEP 6: Analyze and Visualize Results
# ============================================================================
print("\n[6] Analyzing results...")
# Find absorption peak
mask_abs = (wavelengths_abs >= 600) & (wavelengths_abs <= 720)
if np.any(mask_abs):
peak_idx_abs = np.argmax(absorption[mask_abs])
peak_wl_abs = wavelengths_abs[mask_abs][peak_idx_abs]
else:
peak_idx_abs = np.argmax(absorption)
peak_wl_abs = wavelengths_abs[peak_idx_abs]
# Find fluorescence peak
mask_fl = (wavelengths_fl >= 600) & (wavelengths_fl <= 720)
if np.any(mask_fl):
peak_idx_fl = np.argmax(fluorescence[mask_fl])
peak_wl_fl = wavelengths_fl[mask_fl][peak_idx_fl]
else:
peak_idx_fl = np.argmax(fluorescence)
peak_wl_fl = wavelengths_fl[peak_idx_fl]
print(f" ✓ Absorption peak: {peak_wl_abs:.1f} nm")
print(f" ✓ Fluorescence peak: {peak_wl_fl:.1f} nm")
print(f" ✓ Stokes shift: {peak_wl_fl - peak_wl_abs:.1f} nm")
# Plot spectra
fig, ax = plt.subplots(figsize=(10, 6))
ax.plot(wavelengths_abs, absorption, label='Absorption', linewidth=2)
ax.plot(wavelengths_fl, fluorescence, label='Fluorescence', linewidth=2)
ax.axvline(peak_wl_abs, color='C0', linestyle='--', alpha=0.5)
ax.axvline(peak_wl_fl, color='C1', linestyle='--', alpha=0.5)
ax.set_xlabel('Wavelength (nm)', fontsize=12)
ax.set_ylabel('Intensity (arb. units)', fontsize=12)
ax.set_title('Optical Spectra', fontsize=14, fontweight='bold')
ax.legend(fontsize=11)
ax.grid(alpha=0.3)
plt.tight_layout()
plt.savefig('spectra.png', dpi=300)
print(f"\n ✓ Spectra saved to 'spectra.png'")
print("\n✅ Calculation complete!")For a minimal scripting example (when you need automation):
from Alprotein import ProteinStructure, PigmentSystem, ChlorophyllA
# Load structure and build pigment system
protein = ProteinStructure.from_file("structure.pdb", name="MyComplex")
pigment_system = PigmentSystem(protein)
pigment_system.add_pigments_by_residue(
resname="CLA",
pigment_class=ChlorophyllA,
tresp_dict_name="CLA_IPPC",
cdc_dict_name="CLA"
)
# Compute energies and couplings
site_energies = pigment_system.compute_site_energies()
couplings = pigment_system.compute_couplings(method="TrEsp")
print(f"Found {len(pigment_system.pigments)} pigments")
print(f"Mean site energy: {site_energies.mean():.1f} cm⁻¹")💡 Tip: The same workflow is available in the GUI with point-and-click simplicity—no need to remember function names or parameter details!
| Feature | GUI Workbench | Python API |
|---|---|---|
| Learning Curve | Immediate - visual interface | Requires Python knowledge |
| Best For | Exploratory research, single calculations | Automation, batch jobs, pipelines |
| Parameter Selection | Dropdowns with validation | Manual specification |
| Visualization | Built-in interactive plots | Custom matplotlib code |
| Result Export | One-click save | Manual file I/O |
| Reproducibility | Session save/load | Script version control |
| Customization | Guided options | Full programmatic control |
Use both! Start with the GUI to explore and understand your system, then use the Python API when you need to automate or customize.
Alprotein/core/- Core system objects (structure and pigment handling)Alprotein/calculators/- Site energy, coupling, and Hamiltonian calculatorsAlprotein/gui/- Interactive GUI workbench componentsAlprotein/data/- Parameter sets for supported pigment typesexamples/- Runnable scripting examples and workflowstools/- Utility scripts including GUI launcher
MIT License.
If you use Alprotein in published work, please cite:
@software{Alprotein,
title={Alprotein: Interactive GUI and scripting toolkit for excitonic Hamiltonians and optical spectra of molecular aggregates},
author={Mohamed Elrefaiy and Bailey Raber and Doran Raccah},
year={2025},
version={0.2.0},
url={https://github.com/melrefaiy2018/Alprotein},
note={Features interactive GUI workbench for accessible excitonic calculations}
}We welcome contributions! Please read our CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests.
For any questions or support, please reach out to [melrefaiy@utexas.edu].