plotlyMol

Interactive molecular visualizations with Plotly. Supports SMILES, XYZ, MOL/PDB, and cube orbitals.

Features

• 3D ball-and-stick, stick, and VDW representations
• SMILES-to-3D embedding via RDKit
• XYZ, MOL/SDF (single), and PDB input support
• Cube file orbital isosurfaces
• Vibrational mode visualization (Gaussian, ORCA, Molden formats)
  • Static displacement arrows
  • Animated vibrations with interactive controls
  • Heatmap coloring by displacement magnitude
• Dash GUI for interactive exploration

Installation

pip install plotlymol

From source (for development)

git clone https://github.com/The-Schultz-Lab/plotlyMol.git
cd plotlyMol

# Create and activate the conda environment (includes all dependencies)
conda env create -f environment.yml
conda activate plotlymol

# Install the package in editable mode
pip install -e .

Note: Conda is required. If you don't have it, install Miniforge (recommended) or Miniconda. All packages are installed from the conda-forge channel.

Updating the environment

If environment.yml changes after pulling new commits:

conda env update -f environment.yml --prune

Quick start

from plotlymol3d import draw_3D_rep

# Draw a molecule from SMILES
fig = draw_3D_rep(smiles="CCNCOCSC", mode="ball+stick", ambient=0.1)
fig.show()

# Draw from XYZ file
fig = draw_3D_rep(xyzfile="path/to/file.xyz", mode="ball+stick", ambient=0.1)
fig.show()

Orbitals from cube files

from plotlymol3d import draw_3D_rep

fig = draw_3D_rep(
    cubefile="path/to/file.cube",
    molfile="path/to/file.mol",
    mode="ball+stick",
    ambient=0.1,
    cubedraw="orbitals",
    orbital_opacity=0.25,
    orbital_colors=["darkorange", "darkblue"],
)
fig.show()

Vibrational mode visualization

Visualize molecular vibrations from quantum chemistry calculations. Supports Gaussian .log, ORCA .out, and Molden .molden files.

Static displacement arrows:

from plotlymol3d import draw_3D_rep

fig = draw_3D_rep(
    smiles="O",  # Water molecule
    vibration_file="water_freq.log",
    vibration_mode=1,  # First vibrational mode
    vibration_display="arrows",
    vibration_amplitude=1.5,
)
fig.show()

Animated vibration:

from plotlymol3d import parse_vibrations, create_vibration_animation
from rdkit.Chem import MolFromSmiles, AddHs
from rdkit.Chem.AllChem import EmbedMolecule

# Parse vibration data
vib_data = parse_vibrations("water_freq.log")

# Create molecule
mol = MolFromSmiles("O")
mol = AddHs(mol)
EmbedMolecule(mol)

# Generate animation
fig = create_vibration_animation(
    vib_data=vib_data,
    mode_number=1,
    mol=mol,
    amplitude=0.5,
    n_frames=20,  # Smoother with more frames
    mode="ball+stick"
)
fig.show()

Heatmap coloring by displacement:

from plotlymol3d import draw_3D_rep, parse_vibrations, add_vibrations_to_figure

# Create molecular figure
fig = draw_3D_rep(smiles="O", mode="ball+stick")

# Parse vibrations and add heatmap
vib_data = parse_vibrations("water_freq.log")
fig = add_vibrations_to_figure(
    fig=fig,
    vib_data=vib_data,
    mode_number=1,
    display_type="heatmap",
    heatmap_colorscale="Reds"
)
fig.show()

Available parsers:

from plotlymol3d import (
    parse_gaussian_vibrations,  # Gaussian .log files
    parse_orca_vibrations,       # ORCA .out files
    parse_molden_vibrations,     # Molden .molden files
    parse_vibrations,            # Auto-detect format
)

# Auto-detect format from file extension
vib_data = parse_vibrations("calculation.log")

# Access mode data
for mode in vib_data.modes:
    print(f"Mode {mode.mode_number}: {mode.frequency:.1f} cm⁻¹")
    if mode.ir_intensity:
        print(f"  IR Intensity: {mode.ir_intensity:.1f} km/mol")

GUI

Launch the Dash app for interactive controls:

python examples/gui_app.py

Examples

Demo Scripts

• Demo script: python examples/demo_visualizations.py
• Package data includes sample XYZ/MOL/CUBE files under src/plotlymol3d/

Jupyter Notebooks

Vibration Visualization:

• Vibration Visualization Basics - Getting started with vibrational modes
• Advanced Vibration Analysis - Batch processing, IR spectra, publication figures

Performance Testing:

• Performance Benchmarking - Quantitative performance analysis and optimization

Launch notebooks:

jupyter notebook examples/

Performance Testing

Quantitatively measure and optimize rendering performance:

Standalone script:

python tests/test_performance.py

Interactive notebook:

jupyter notebook examples/performance_benchmarking.ipynb

Full guide: docs/PERFORMANCE_TESTING_GUIDE.md (coming soon)

Key metrics tracked:

• Rendering time vs molecule size
• Resolution impact (8-64)
• Memory usage profiling
• Vibration parsing speed
• Animation generation performance

Use these tools to identify bottlenecks and optimize GUI responsiveness.

Repository layout

plotlyMol/
├─ src/
│  └─ plotlymol3d/        # Library package code + sample data files
├─ examples/              # Demo scripts and GUI app
├─ tests/                 # Pytest suite
├─ docs/                  # Roadmap and documentation assets
├─ pyproject.toml          # Packaging and tooling configuration
├─ requirements.txt        # Consolidated dependencies
└─ README.md

Roadmap

See GitHub Issues for planned features and upcoming work.