96 online 3 members  + Join RP Base  +
FreeTool

vorpy

by jackericson98  ·  version 2.0.0  ·  updated 3 days ago

No reviews yet

Downloads
0
Reviews
0
Size
34.3 MB
Code check
Clean
Licence
MIT
Released
Nov 2026

Molecular partitioning tool for simulated atoms using Delaunay, Power and Voronoi cells

vorpy
VorPy
Quantitative molecular geometry through three-dimensional spatial partitioning

Overview
VorPy is a Python framework for constructing and analyzing three-dimensional Voronoi partitions of molecular and other spherical systems.

VorPy represents atoms or other objects as spheres and partitions space using three complementary geometric schemes:

  • Additively weighted (AW) Voronoi diagrams
  • Power (Laguerre) diagrams
  • Primitive (unweighted) Voronoi diagrams

From these decompositions, VorPy can quantify volume, surface area, neighbors, contacts, interfaces, exposure, surface geometry, curvature, and related molecular properties. Analyses can be performed at the level of atoms, residues, chains, molecules, user-defined groups, and interfaces between groups.

VorPy provides both a graphical user interface (GUI) for interactive analysis and a command-line interface (CLI) for reproducible, automated, and large-scale workflows.

Molecular structure is fundamentally geometric. Changes in packing, exposure, local contacts, and intermolecular interfaces alter how atoms occupy and share space. VorPy provides a common spatial framework for quantifying these relationships.

InstallationPyPI
pip install vorpy3

Conda
conda install vorpy3

Development checkout
To run the current code from a clone, including the new Analysis Studio GUI,
install the checkout in editable mode with its GUI dependencies:

git clone https://github.com/jackericson98/vorpy.git
cd vorpy
python -m pip install -e ".[gui]"

Alpha-complex workflows that use GUDHI are optional:

python -m pip install "vorpy3[gudhi]"

The core physical geometry path does not require GUDHI. The published GUI
extra installs PySide6, PyVista, and PyVistaQt; the Conda package currently
follows the core/headless dependency contract.

This keeps the installed vorpy command connected to the checkout, so future
git pull updates take effect without reinstalling. The repository root also
contains double-clickable application launchers:

  • Linux: vorpy-linux.desktop (or run ./vorpy-linux)
  • macOS: vorpy-mac.command
  • Windows: vorpy-windows.bat

Each launcher creates a local .venv and installs the GUI dependencies
automatically when needed. The first run displays installation progress and may
take several minutes. Later launches skip setup, detach from the terminal, and
show a VorPy splash while the 3D stack loads. A lightweight installer window
shows the VorPy logo and package installation log during first-time setup.
Intel Macs automatically use the final Numba release that provides native
Intel macOS wheels, avoiding a local LLVM/CMake build.

On GNOME-based Linux desktops, a newly cloned .desktop file may need to be
trusted once before it can be opened by double-clicking:

chmod +x vorpy-linux.desktop vorpy-linux
gio set -t string vorpy-linux.desktop metadata::trusted true

Your file manager may also offer this as Allow Launching in the launcher's
right-click menu. If launching .desktop files directly from a folder is
disabled, run ./vorpy-linux or install the desktop entry into the system's
application menu.

VorPy currently targets Python 3.10+. Explicit multi-version support will be listed here once the test suite and end-to-end regression suite have been validated across supported interpreters and platforms.

Quick Start
Launch the graphical interface:

vorpy

Open the file browser:

vorpy browse

Analyze a structure directly:

vorpy path/to/structure.pdb

VorPy currently supports .pdb, .cif, .mol, .mol2, and .gro files.

Spatial Partitioning Schemes**Additively weighted Voronoi (aw)**
Accounts directly for sphere radii through distance to sphere surfaces, making it well suited to radius-aware molecular geometry.
**Power / Laguerre (pow)**
Incorporates sphere size through power distance while retaining planar cell boundaries.
**Primitive (prm)**
Depends only on generator positions. Sphere radii do not affect boundary placement, making it useful as an unweighted geometric reference.

VorPy supports direct comparison between these schemes so the effects of the chosen spatial model can be evaluated explicitly.

Molecular Geometry
Depending on the requested analysis and exports, VorPy can provide information about:

  • Voronoi cell volume
  • molecular and cell surface area
  • neighboring atoms and cells
  • contact topology
  • interfacial surface area
  • solvent-facing exposure
  • cell shape descriptors
  • local and integrated curvature
  • triangulated surfaces
  • edges and vertices
  • atom, residue, chain, group, and system summaries

Interface Analysis
Interface analysis is one of VorPy's central molecular-analysis capabilities.

Groups of atoms can be defined independently and their shared Voronoi boundaries analyzed as explicit geometric interfaces. This supports protein-protein, protein-DNA, protein-RNA, protein-ligand, solute-solvent, chain-chain, residue-residue, and arbitrary user-defined interfaces.

Because interfaces are derived from shared Voronoi boundaries, VorPy can describe not only which atoms are neighbors, but also the geometry and area of the boundary shared between them.

See [docs/molecular_analysis/interfaces.md](https://github.com/jackericson98/vorpy/blob/master/docs/molecular_analysis/interfaces.md).

Groups and Selections
VorPy analyses can operate on the full structure or on selected subsets.

Selections can be based on:

  • atom indices
  • residue indices
  • chain indices
  • molecule indices
  • molecular classes such as protein, ligand, DNA, and RNA
  • structural identities such as a specific chain or residue

Examples of increasingly specific selections include:

protein
dna
chain A
THY 124

The exact CLI syntax for identity-based selectors is being expanded and will be documented in the full

…