Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings

The-Schultz-Lab/plotlyMol

Open more actions menu
 
 

Repository files navigation

plotlyMol

plotlyMol Logo

Tests Lint License: MIT

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:

Performance Testing:

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.

About

Interactive 3D molecular visualization in Python — ball-and-stick, VDW, orbital rendering, and a Dash GUI. Built on Plotly and RDKit.

Topics

Resources

License

Contributing

Stars

Watchers

Forks

Packages

 
 
 

Contributors

Languages

  • Python 99.5%
  • Other 0.5%
Morty Proxy This is a proxified and sanitized view of the page, visit original site.