Basic Usage

A quick-start walk-through focused on the core beginner workflow. For full details on every feature see the Functionality Guide; for copy-paste snippets see Quick Recipes.

Import and load structures

from pdb_cpp import Coor

# Load from local file (PDB, mmCIF, PQR, or GRO — auto-detected by extension)
coor = Coor("tests/input/1y0m.cif")

# Load from PDB ID (downloaded as mmCIF and cached locally)
coor_from_id = Coor(pdb_id="1y0m")

# Load explicitly from the RCSB helper
from pdb_cpp import rcsb

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

Use Coor(pdb_id=...) when you only need the deposited mmCIF entry. Use pdb_cpp.rcsb when you want explicit control over which RCSB file is fetched, including biological assemblies, cache location, or forced re-download.

Inspect a structure

print(coor.model_num)            # number of models
print(coor.len)                  # number of atoms in active model
print(coor.get_uniq_chain())     # list of chain IDs

# Coordinates, atom names, residue names
print(coor.xyz[:5])              # shape (N, 3)
print(coor.name_str[:5])         # ['N', 'CA', 'C', 'O', 'CB']
print(coor.resname_str[:5])      # ['THR', 'THR', ...]
print(coor.chain_str[:5])        # ['A', 'A', ...]
print(coor.resid[:5])            # residue sequence numbers
print(coor.beta[:5])             # B-factors
print(coor.occ[:5])              # occupancies

See the Functionality Guide for the complete list of Coor and Model properties.

Atom selections

chain_a = coor.select_atoms("chain A")
backbone = coor.select_atoms("protein and backbone")
interface = coor.select_atoms("chain A and within 5.0 of chain B")
indices = coor.get_index_select("name CA and chain A")

See the Functionality Guide for the full selection syntax, including keywords, operators, and spatial queries.

Write output

chain_a.write("chain_A.pdb")
chain_a.write("chain_A.cif")

Sequence alignment and structural superposition

from pdb_cpp import alignment, core, analysis

coor_1 = Coor("tests/input/1u85.pdb")
coor_2 = Coor("tests/input/1ubd.pdb")

# One-step sequence-based alignment + RMSD
rmsd_list, _, _ = core.align_seq_based(coor_1, coor_2, chain_1=["A"], chain_2=["C"])
print(f"RMSD: {rmsd_list[0]:.3f} Å")

Next steps

From here, pick the page that matches your goal: