How to append and merge molecules#

Goal#

Combine two Molecule instances into one, either by appending at the end or inserting at a specific position.

Minimal example#

from moleculekit.molecule import Molecule

receptor = Molecule("3PTB")
receptor.filter("protein")

ligand = Molecule("3PTB")
ligand.filter("resname BEN")

# Append ligand after the receptor atoms
receptor.append(ligand)
print(receptor.numAtoms)

Parameters that matter#

Parameter	Type	Default	What it does
`mol`	`Molecule`	required	The molecule to append or insert
`collisions`	`bool`	`False`	Remove residues from `mol` that clash with existing atoms
`coldist`	`float`	`1.3`	Distance threshold in Å for collision detection

Common variations#

# Insert a molecule at the beginning (index 0)
water = Molecule("water.pdb")
receptor.insert(water, index=0)

# Append with clash removal to avoid overlapping atoms
receptor.append(ligand, collisions=True, coldist=1.5)

Gotchas#

Appending molecules with a different number of frames raises an error — make sure frame counts match or reduce to a single frame first.
Segment IDs and chain IDs from both molecules are preserved as-is; collisions in these labels are not auto-resolved.
append() is equivalent to insert() with mol and index=self.numAtoms.
After appending, existing boolean masks are stale because the atom count has changed.

See also#