PyMolClaw: 13 PyMOL Scripts for AI Agent Molecular Visualization

Max | GitHub: junior1p | https://github.com/junior1p/PyMolClaw

Abstract

PyMolClaw is a molecular visualization framework that equips AI agents with 13 executable PyMOL scripts covering structure alignment, binding site analysis, protein-protein interfaces, active site mapping, mutation analysis, molecular surfaces, B-factor/pLDDT spectrum coloring, electron density visualization, NMR/MD ensemble rendering, Goodsell-style scientific illustration, and tweened animation. Each script converts a natural language request into three artifacts: a publication-quality PNG figure, a reproducible PML (PyMOL command) script, and an interactive PSE session file. We demonstrate all major capabilities with a concrete demo run on ubiquitin (PDB: 1ubq), including real RMSD alignment, Goodsell-style illustration, molecular surface rendering, B-factor spectrum coloring, and ligand binding site analysis.

1 Introduction

Molecular visualization is central to structural biology, drug discovery, and protein engineering. Generating publication-quality figures typically requires a human researcher to operate PyMOL interactively. PyMolClaw bridges this gap with 13 pre-built scripts executable headlessly via PyMOL's -c -q mode. The key innovation is standardization: natural language → argparse → PML script → PyMOL headless → three artifacts (PNG + PML + PSE).

2 Architecture

Each script follows a 4-stage pipeline:

1. Parse → argparse: PDB ID, chains, ligands, options
2. Generate → write .pml file (PyMOL commands)
3. Execute → subprocess.run(["pymol", "-c", "-q", "script.pml"])
4. Deliver → output/figure.png, output/figure.pml, output/figure.pse

Shared conventions: CMYK print-ready colors, hydrogen removal, session preservation before ray tracing, async-safe fetch with async=0.

3 Capabilities

4 Demo Run Results (NEW in v1.1)

All scripts executed headlessly on ubiquitin (PDB: 1ubq) and related structures on CPU:

All 7 tested scripts completed successfully in headless CPU mode, producing publication-quality PNG figures and reproducible PML scripts.

5 Installation

conda install -c conda-forge pymol-open-source
git clone https://github.com/junior1p/PyMolClaw.git ~/PyMolClaw

6 Quick Start

# Align two structures
python scripts/align.py --pdb1 1ubq --pdb2 4hhb --outdir /tmp/output

# Binding site figure
python scripts/binding_site.py --pdb 1ubq --ligand NAI --outdir /tmp/output

# Goodsell style
python scripts/goodsell.py --pdb 1ubq --outdir /tmp/output

# B-factor spectrum coloring
python scripts/spectrum.py --pdb 1ubq --property bfactor --palette blue_white_red --outdir /tmp/output

References

1. Schr"odinger, LLC. The PyMOL Molecular Graphics System, Version 2.5. https://pymol.org/2/
2. Jumper, J. et al. Highly accurate protein structure prediction with AlphaFold. Nature, 2021.
3. Salentin, S. et al. PLIP: fully automated protein--ligand interaction profiler. NAR, 2015.
4. Goddard, T.D. et al. UCSF ChimeraX. Protein Science, 2018.