MolR - Molecular Realm for Spatial Indexed Structures

A high-performance Python package that creates a spatial realm for molecular structures, providing lightning-fast neighbor searches, geometric queries, and spatial operations through integrated KDTree indexing.

Features

High-Performance Structure Representation

• NumPy-based Structure class with Structure of Arrays (SoA)
• Efficient spatial indexing with scipy KDTree integration for O(log n) neighbor queries
• Memory-efficient trajectory handling with StructureEnsemble
• Lazy initialization of optional annotations to minimize memory usage

Comprehensive Bond Detection

• Hierarchical bond detection with multiple providers:
  • File-based bonds from PDB CONECT records and mmCIF data
  • Template-based detection using standard residue topologies
  • Chemical Component Dictionary (CCD) lookup for ligands
  • Distance-based detection with Van der Waals radii
• Intelligent fallback system ensures complete bond coverage
• Partial processing support for incremental bond detection

Powerful Selection Language

• MDAnalysis/VMD-inspired syntax for complex atom queries
• Spatial selections with within, around, and center-of-geometry queries
• Boolean operations (and, or, not) for combining selections
• Residue-based selections with byres modifier

Multi-Format I/O Support

• PDB format with multi-model support and CONECT record parsing
• mmCIF format with chemical bond information extraction
• Auto-detection of single structures vs. trajectories
• String-based parsing for in-memory structure creation

Installation

pip install molr

For development installation:

git clone https://github.com/abhishektiwari/molr.git
cd molr
pip install -e .[dev]

Requirements

• Python ≥3.8
• NumPy ≥1.20.0
• SciPy ≥1.7.0 (for spatial indexing)
• pyparsing ≥3.0.0 (for selection language)

Usage

Please review Molr documentation for more details on how to use Molr for various use cases.

Quick Example

import molr

# Load a structure
structure = molr.Structure.from_pdb("protein.pdb")

# Detect bonds
bonds = structure.detect_bonds()

# Use selection language
active_site = structure.select("within 5.0 of (resname HIS)")

# Fast spatial queries
neighbors = structure.get_neighbors_within(atom_idx=100, radius=5.0)

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

See our contributing guide and development guide. At a high-level,

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request