VMDHole

VMDHole is a VMD plugin for analysing pores and molecular tunnels. Pore mode runs HOLE along a specified channel axis. Tunnel mode searches from a buried point for routes to the molecular surface. Results remain linked to the VMD structure and trajectory.

Documentation · Install · First analysis · Parameter reference

What VMDHole adds

VMDHole brings pore and tunnel analysis into one trajectory-aware VMD workflow. Instead of treating structures, pathways, hydration, and visualization as separate tasks, it keeps them linked to the same molecule and simulation frame.

• Pores and tunnels in one place. Analyze channel pores or routes from buried sites to the surface, then measure their geometry, bottlenecks, lining residues, and chemical properties.

• More than a single pore radius. Choose spherical, Connolly, or capsule pore models for round, irregular, or slit-like channels. Tunnel routes can be ranked, clustered, and followed across a trajectory.

• Structure linked to dynamics. Examine how geometry, hydration, free energy, and ion movement change frame by frame through synchronized plots and live 3D views.

• Built for trajectories. Parallel frame processing and compiled acceleration make large ensemble analyses practical while retaining interactive visualization in VMD.

• Results ready to use. Export pathway properties, plots, and figures for further analysis, publication, or reproducible workflows.

Performance

Full numbers, provenance and the replication kit: paper/README.md.

Install

VMDHole is a Tcl plugin, but native analysis binaries are strongly recommended. The bundled Tcl fallbacks maximize compatibility; they are much slower and are not the recommended path for trajectories or production calculations.

1. Install the plugin

1. Download and extract a VMDHole release, or clone this repository.

2. Add the directory containing vmdhole to VMD's Tcl path and load the package from .vmdrc:

   lappend auto_path /absolute/path/to/VMDHole
   package require vmdhole 1.0

3. Restart VMD and open Extensions → Analysis → VMDHole.

2. Install the native binaries (highly recommended)

Use the binary bundle attached to the same VMDHole release when one is available for your operating system and CPU. For the best performance and compatibility, rebuild the native tools locally.

Local-build requirements:

• a POSIX shell, make, and Python 3;
• a C compiler and a Fortran compiler with legacy Fortran support;
• OpenMP compiler support for the parallel Connolly and sph_process accelerators;
• Git and network access only when the script must download HOLE 2 for you.

From the repository, run:

./native/build-vmdhole-optimized.sh

With no argument, the script downloads the pinned HOLE 2 source and builds into native/build/. To use an existing source tree or another output location, pass either absolute or relative paths:

./native/build-vmdhole-optimized.sh /any/path/to/hole2/src /any/output/path

In VMDHole, open File → Settings and select the resulting hole, sph_process, sos_triangle (which also carries the marching-cubes mesher, the Nelder-Mead search and the Connolly classifier), and mole_tunnel_engine executables.

See the installation guide for platform requirements, binary choices, verification, and upgrades.

Minimal examples

Pore

The distribution includes gramicidin A at vmdhole/1GRM.pdb.

1. Load the PDB in VMD.
2. Open VMDHole and select Pore mode.
3. Set Selection to all and Frames to now.
4. Keep the proposed CPOINT and CVECT, or define the direction with the ⌖ dialog beside CVECT (two points, or a stick that tilts it).
5. Enable Show cues under the HOLE parameters gear and confirm that the point and arrow follow the channel.
6. Select Run HOLE.

Tunnel

1. Load vmdhole/1MXT.pdb in VMD.
2. Select Tunnel, set Selection to protein, and set Frames to now.
3. Enable Auto-detect origins (scan whole structure).
4. Select Run Tunnel.

For complete worked examples, choose a path in the tutorials.

Scientific scope

Pore mode follows a specified channel axis. Spherical HOLE estimates the largest non-overlapping probe sphere at successive positions; Connolly and Capsule supply alternative cross-sectional models. Results depend on the atom selection, radius file, starting point, direction, sampling interval, method, and stochastic-search settings. Report these inputs with derived radius, volume, or conductance values.

Tunnel mode answers a different geometric question: which routes connect a buried origin to the molecular surface? Its ranked and clustered routes are candidate pathways, not proof that a ligand, solvent molecule, or ion uses them.

Water free energy, ion occupancy, passage, and permeation analyses depend on the sampling and preparation of the supplied trajectory. A geometric opening or conductance estimate is not evidence of biological permeation; support such claims with suitable simulation or experimental data.

Citation and notices

For every VMDHole analysis, cite VMDHole, VMD, and HOLE. Additional citations depend on the features used, for example MOLE 2 for tunnel searches, CAVER 3.0 for tunnel clustering, and CHAP for CHAP-compatible hydration analysis. Open Help → Guide & Citations… → Citations in the plugin or consult References for the exact method-specific references.

VMDHole's original plugin code is MIT-licensed. The installed folder also contains a pure-Tcl derivative of Apache-2.0 HOLE 2 code; retain vmdhole/LICENSE-Apache-2.0.txt and vmdhole/NOTICE.md. The optional native derivative has its own LICENSE and NOTICE. See LICENSE, vmdhole/NOTICE.md, and native/NOTICE.