pdb_cpp

pdb_cpp is a structural bioinformatics toolkit with a C++ core and Python API for fast PDB/mmCIF parsing, atom selection, sequence/structure alignment, TM-score, and DockQ evaluation.

What is included

• Read/write .pdb, .cif, .pqr, and .gro files
• Atom/residue/chain selections (including geometric within queries)
• Sequence extraction and pairwise sequence alignment
• Sequence-based structural superposition and chain-permutation alignment
• TM-align/TM-score through the bundled USalign/TM-align core
• DockQ metrics (DockQ, Fnat, Fnonnat, LRMS, iRMS, rRMS)
• Hydrogen bond detection (Baker & Hubbard geometric method, no explicit H required)
• Solvent-accessible surface area (Shrake-Rupley) on Model, plus buried protein-protein surface and shape-complementarity helpers
• Secondary structure assignment
• Core geometric helpers (e.g., distance matrix)

Installation

From PyPI

python -m pip install pdb-cpp

From source

git clone https://github.com/samuelmurail/pdb_cpp
cd pdb_cpp
python -m pip install -e .

For development:

python -m pip install -r requirements.txt
pytest

Quick start

from pdb_cpp import Coor

# Load from local file
coor = Coor("tests/input/1y0m.cif")

# Or fetch by PDB ID (mmCIF is downloaded and cached)
coor_pdb = Coor(pdb_id="1y0m")

# Or use the RCSB helper for explicit structure choices
from pdb_cpp import rcsb

bio_assembly = rcsb.load("5a9z", structure="biological_assembly", assembly_id=1)
asym_unit = rcsb.load("5a9z", structure="asymmetric_unit")

print(coor.model_num)        # number of models
print(coor.get_aa_seq())     # chain -> sequence

# Write selection/structure back to disk
coor.write("out_structure.pdb")

Documentation map

For complete usage documentation, use the project docs site and source pages:

• Basic tutorial: docs/source/basic_example.md
• Full feature guide: docs/source/functionality.md
• Copy-paste recipes: docs/source/quick_recipes.md
• Installation and build notes: docs/source/installation.md
• API reference entry: docs/source/pdb_cpp.rst

Online docs: https://samuelmurail.github.io/pdb_cpp/

Documentation

• API and examples: https://samuelmurail.github.io/pdb_cpp/
• Docs sources: docs/source/

Notes for contributors (C++ core)

When adding C++ features:

1. Add implementation files in src/pdb_cpp/_core/
2. Register sources in setup.py
3. Expose bindings in src/pdb_cpp/_core/pybind.cpp
4. Reinstall extension (pip install -e . --no-build-isolation) and run tests