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

fromplotlymol3dimportdraw_3D_rep# Draw a molecule from SMILESfig=draw_3D_rep(smiles="CCNCOCSC", mode="ball+stick", ambient=0.1)
fig.show()
# Draw from XYZ filefig=draw_3D_rep(xyzfile="path/to/file.xyz", mode="ball+stick", ambient=0.1)
fig.show()

Orbitals from cube files

fromplotlymol3dimportdraw_3D_repfig=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:

fromplotlymol3dimportdraw_3D_repfig=draw_3D_rep(
smiles="O", # Water moleculevibration_file="water_freq.log",
vibration_mode=1, # First vibrational modevibration_display="arrows",
vibration_amplitude=1.5,
)
fig.show()

Animated vibration:

fromplotlymol3dimportparse_vibrations, create_vibration_animationfromrdkit.ChemimportMolFromSmiles, AddHsfromrdkit.Chem.AllChemimportEmbedMolecule# Parse vibration datavib_data=parse_vibrations("water_freq.log")
# Create moleculemol=MolFromSmiles("O")
mol=AddHs(mol)
EmbedMolecule(mol)
# Generate animationfig=create_vibration_animation(
vib_data=vib_data,
mode_number=1,
mol=mol,
amplitude=0.5,
n_frames=20, # Smoother with more framesmode="ball+stick"
)
fig.show()

Heatmap coloring by displacement:

fromplotlymol3dimportdraw_3D_rep, parse_vibrations, add_vibrations_to_figure# Create molecular figurefig=draw_3D_rep(smiles="O", mode="ball+stick")
# Parse vibrations and add heatmapvib_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:

fromplotlymol3dimport (
parse_gaussian_vibrations, # Gaussian .log filesparse_orca_vibrations, # ORCA .out filesparse_molden_vibrations, # Molden .molden filesparse_vibrations, # Auto-detect format
)
# Auto-detect format from file extensionvib_data=parse_vibrations("calculation.log")
# Access mode dataformodeinvib_data.modes:
print(f"Mode {mode.mode_number}: {mode.frequency:.1f} cm⁻¹")
ifmode.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.