molpacd 0.1.0

Molecular Pore Aperture Cap Designer

MolPACD

MolPACD is the Molecular Pore Aperture Cap Designer. It designs, adds, analyzes, and removes molecular aperture caps in protein structures.

The first implementation is derived from the MemGen beta-barrel water-cap script, but generalizes the workflow for PDB and mmCIF structures with configurable axes, cap identity, and cap removal metadata.

Install

From PyPI:

python -m pip install molpacd

From a local checkout:

python -m pip install .

For development:

python -m pip install -e ".[dev]"

With Conda, keep the environment local to the checkout:

conda env create -p .conda/molpacd-dev -f environment-dev.yml
conda run -p .conda/molpacd-dev python -m nox -s lint format mypy tests-3.13 build

Common development tasks are also available through make:

make env
make check

For documentation work:

make docs-deps
make docs-serve

CLI

Analyze candidate apertures:

molpacd analyze input.pdb --json

Add caps to both apertures:

molpacd add input.pdb -o capped.pdb

Use a membrane-oriented z-axis and a fixed cap residue name:

molpacd add input.pdb -o capped.pdb --axis z --resname DUM

Use each aperture's inferred radius instead of sharing the larger radius:

molpacd add input.pdb -o capped.pdb --axis z --independent-radius

Remove MolPACD-generated caps:

molpacd remove capped.pdb -o decapped.pdb

Remove matching caps from a file without MolPACD metadata:

molpacd remove capped.pdb -o decapped.pdb --resname DUM --chain Z --force

MolPACD writes cap provenance metadata and uses it during removal so matching non-cap atoms are not removed accidentally. If metadata is absent, or if you override metadata values such as residue name, chain, or atom name, removal requires --force.

Format Notes

MolPACD reads PDB and mmCIF files and writes minimal PDB/mmCIF outputs focused on atom records plus MolPACD metadata. It preserves PDB header lines before the coordinate section, but it does not attempt to reproduce every original record or mmCIF category. Multi-model structures are not supported for analysis or cap addition; split those structures into single-model inputs before running MolPACD.

Library

from pathlib import Path

from molpacd import CapOptions, add_caps, read_structure, write_structure

structure = read_structure(Path("input.pdb"))
capped, result = add_caps(structure, CapOptions(axis="z", resname="DUM"))
write_structure(capped, Path("capped.pdb"))

print(result.resname, result.added_count)

Development Checks

python -m nox

The nox sessions run tests, linting, formatting checks, type checks, and package build validation. GitHub Actions runs the same checks on pushes and pull requests.

Documentation

The project documentation is built with MkDocs:

make docs