ChiralFold

Chirality-correct protein stereochemistry toolkit — audit any PDB, fix AF3 chirality errors, build D-peptides by construction, and generate exact L↔D mirrors.

Start here

Install

Works on Linux, macOS, and Windows (Python 3.9–3.12).

# Recommended — always current (PyPI package pending Trusted Publisher setup)
pip install -U pip
pip install "chiralfold @ git+https://github.com/Tommaso-R-Marena/ChiralFold.git@v3.5.1"

# Or clone + editable
git clone https://github.com/Tommaso-R-Marena/ChiralFold.git
cd ChiralFold
pip install -e .

Note: Bare pip install chiralfold requires PyPI publishing to succeed. See docs/PYPI_PUBLISHING.md for Trusted Publisher setup (or set secret PYPI_API_TOKEN). Until then, use the Git install above — same package.

Core dependencies: numpy, scipy, pandas, rdkit.
Optional: pip install "chiralfold[web]" (Gradio UI) · pip install "chiralfold[viz]" (matplotlib/seaborn for benchmarks).

If rdkit fails on your platform:

conda install -c conda-forge rdkit
pip install "chiralfold @ git+https://github.com/Tommaso-R-Marena/ChiralFold.git"

Full platform notes: docs/INSTALL.md.

# Verify
python -c "import chiralfold; print(chiralfold.__version__)"
chiralfold --help

Reviewer path (<5 minutes, offline)

Reproduce the 29 D-label / L-coordinate mismatches from the frozen survey CSV — no network, no ChiralFold install required beyond numpy:

git clone --depth 1 https://github.com/Tommaso-R-Marena/ChiralFold.git
cd ChiralFold
pip install numpy   # only dependency for this script
python benchmarks/reproduce_d_residue_errors.py

Expected output: 12,573 checkable residues · 29 errors · 16 structures · rate 0.23%.

Or open the Reproduce D-residue errors Colab.

What ChiralFold does

from chiralfold import audit_pdb, correct_af3_output, mirror_pdb, ChiralFold

report = audit_pdb("protein.pdb")          # chirality, Rama, clashes, score
correct_af3_output("af3.pdb", "fixed.pdb") # fix inverted stereocenters
mirror_pdb("1YCR.pdb", "1YCR_D.pdb")       # exact L↔D (RMSD 0.0 Å)
pred = ChiralFold().predict("AFWKELDR")     # D-peptide, 0% violations by construction

Web UI (local):

pip install "chiralfold[web]"
chiralfold-web   # http://localhost:7860

Key results (at a glance)

MolProbity does not flag the D-residue annotation errors (L-only Cα check).

Unusual cases

ChiralFold is tested on structures that break naive assumptions:

See demos/Demo_Unusual_Cases_Clash_Safety.ipynb and results/5m2k_benchmark_exclusion.json.

“By construction” does not invent clashes

• Mirror L↔D is a global isometry: all pairwise distances are preserved → clashscore is identical before and after (tests/test_clash_preservation.py).
• AF3 chirality correction reflects only the violating Cα across the N–C–Cβ plane, preserving CA–N / CA–C / CA–Cβ bond lengths. Clashscore may change slightly when a bad stereocenter is fixed; residual chirality violations go to 0%.

Repository map

chiralfold/          # Installable Python package
web/                 # Gradio UI (chiralfold-web)
hf_space/            # Hugging Face Space source
demos/               # Colab notebooks (start with Reproduce_PDB_D_Residue_Errors_5min)
benchmarks/          # Reproducible survey / validation / Rama scripts
results/             # Frozen CSV/JSON artefacts (do not hand-edit)
tests/               # pytest suite
paper/submission/    # Bioinformatics Overleaf package
docs/                # Install notes, navigation

Citation

@software{chiralfold2026,
  author = {Marena, Tommaso R.},
  title  = {ChiralFold: Chirality-correct protein stereochemistry toolkit},
  year   = {2026},
  url    = {https://github.com/Tommaso-R-Marena/ChiralFold}
}

AF3 D-peptide context: Childs, Zhou & Donald (2025) bioRxiv 10.1101/2025.03.14.643307.

License

MIT — see LICENSE.