cgback 1.0.3

Deep learning tool for backmapping coarse-grained to all-atom

CGBack

CGBack is a Python tool for backmapping coarse-grained structures into all-atom models using a diffusion-based generative model. It supports various model sizes, GPU acceleration, energy minimization with OpenMM, and reproducibility features.

---

📦 Installation

You can install CGBack using pip:

pip install cgback

or using uv:

uv tool install cgback

🧩 Dependencies

CGBack requires Python 3.10 or higher and the following Python packages:

Package	Version	Description
numpy	≥ 2.1.0	Numerical computations
scipy	≥ 1.15.0	Scientific computing utilities
torch	≥ 2.5.0	PyTorch deep learning framework
rich	≥ 13.9.4	Pretty terminal output

Additionally, to enable energy minimization, CGBack requires the following Python package:

Package	Version	Description
openmm	≥ 8.2.0	Molecular dynamics

🔧 Specific Sources (optional)

To install PyTorch for a specific CUDA version, please use the appropriate index:

For CUDA 11.8:

# using pip
pip install cgback --extra-index-url https://download.pytorch.org/whl/cu118

# using uv
uv tool install cgback --index pytorch=https://download.pytorch.org/whl/cu118

For CUDA 12.1:

# using pip
pip install cgback --extra-index-url https://download.pytorch.org/whl/cu121

# using uv
uv tool install cgback --index pytorch=https://download.pytorch.org/whl/cu121

For CUDA 12.4:

# using pip
pip install cgback --extra-index-url https://download.pytorch.org/whl/cu124

# using uv
uv tool install cgback --index pytorch=https://download.pytorch.org/whl/cu124

For CUDA 12.6:

# using pip
pip install cgback --extra-index-url https://download.pytorch.org/whl/cu126

# using uv
uv tool install cgback --index pytorch=https://download.pytorch.org/whl/cu126

For CUDA 12.8:

# using pip
pip install cgback --extra-index-url https://download.pytorch.org/whl/cu128

# using uv
uv tool install cgback --index pytorch=https://download.pytorch.org/whl/cu128

To enable energy minimization, please add OpenMM support.

For OpenMM with CPU and OpenCL support:

# using pip
pip install 'cgback[openmm]'

# using uv
uv tool install 'cgback[openmm]'

For OpenMM with CUDA 12 support:

# using pip
pip install 'cgback[openmm-cuda12]'

# using uv
uv tool install 'cgback[openmm-cuda12]'

❗Note: When running CGBack with OpenMM support enable for the first time, you may encounter several warnings. These messages are generated by the OpenMM package and do not indicate a problem with CGBack itself. The OpenMM team is expected to resolve them in a future update. You can safely ignore these warnings.The installation and functionality of CGBack remain unaffected.

⚙️ Installation examples

Example of an installation using PyTorch and OpenMM, both only with CPU support:

# using pip
pip install 'cgback[openmm]' --extra-index-url https://download.pytorch.org/whl/cpu

# using uv
uv tool install 'cgback[openmm]' --index pytorch=https://download.pytorch.org/whl/cpu

Example of an installation using PyTorch with CUDA 12.6 and OpenMM with CUDA 12:

# using pip
pip install 'cgback[openmm-cuda12]' --extra-index-url https://download.pytorch.org/whl/cu126

# using uv
uv tool install 'cgback[openmm-cuda12]' --index pytorch=https://download.pytorch.org/whl/cu126

🚀 Quick Start

The basic usage is very simple, just pass the coarse-grained structure to CGBack:

cgback input.pdb

The all-atom structure will be saved as out.pdb

📚 Examples

Basic backmapping:

cgback input.pdb # PDB format
cgback input.cif # PDBx/mmCIF format

Backmapping using different output formats:

cgback input.pdb -o out.pdb # Input in PDB format, output in PDB format
cgback input.cif -o out.cif # Input in PDBx/mmCIF format, output in PDBx/mmCIF format
cgback input.pdb -o out.cif # Input in PDB, output in PDBx/mmCIF format
cgback input.cif -o out.pdb # Input in PDBx/mmCIF format, output in PDB format

Backmapping using GPU:

cgback input.pdb -d cuda # on CUDA systems
cgback input.pdb -d mps  # on Apple systems

Backmapping using different models:

cgback input.pdb -m S  # Small model
cgback input.pdb -m M  # Medium model (default)
cgback input.pdb -m L  # Large model

Verbose output and logging:

cgback input.pdb -v

Save intermediate files:

cgback input.pdb -k

Energy Minimization with OpenMM (requires enabling support for OpenMM):

cgback input.pdb -e

🧪 Advanced Usage

Generate different outputs with controlled random seeds:

cgback input.pdb -s 1
cgback input.pdb -s 2

Specify the number of diffusion steps manually:

cgback input.pdb -n 150

Change batch size for larger or smaller memory usage:

cgback input.pdb -b 128

Customize energy minimization tolerance and iterations (in this case with a tolerance of 5.0 kJ/mol and 1000 minimization iterations):

cgback input.pdb -e --energy-minimization-tolerance 5.0 --energy-minimization-max-iterations 1000

Skip fixing atomic clashes during refinement:

cgback input.pdb --skip-fix-structure-clashes

Perform only backmapping, skipping adding hydrogen atoms, and skipping the whole refinement step:

cgback input.pdb --skip-add-hydrogen --skip-fix-structure

✨ Extra Usage

CGBack can act as a lightweight structure‑repair tool, no coarse‑grained input required. Here are four handy one‑liners you can drop into your workflow:

1. Add missing hydrogen atoms:

# input.pdb is a heavy‑atom model that lacks H-atoms
cgback input.pdb # out.pdb with idealised H‑atoms added

Hydrogen atoms are placed according to standard protonation states at pH7±0.5. Combine with -e (energy minimization) if you want a quick local relaxation.

2. Mutate a residue in‑place:

# Prepare input.pdb so the target residue:
#  • is renamed to the desired three‑letter code (e.g. ALA → LYS)
#  • keeps only its CA atom
cgback input.pdb # out.pdb with the rebuilt target residue

CGBack reconstructs the full side‑chain, stitches it into the existing backbone, and removes clashes.

3. Fix structural artifacts:

# input.pdb has atoms poking through aromatic rings
cgback input.pdb # out.pdb with penetrations resolved and stereochemistry repaired

CGBack detects atoms that intrude an aromatic ring plane and re‑positions them to a clash‑free site. It also scans all chiral centers and regenerates one in the canonical form. Combine with -e (energy minimization) if you want a quick local relaxation.

🧬 Citation

If you use CGBack in your research, please cite the following paper:

Ugarte La Torre, D., Sugita, Y.; CGBack: Diffusion Model for Backmapping Large-Scale and Complex Coarse-Grained Molecular Systems, bioRxiv 2025.06.04.657965; doi: https://doi.org/10.1101/2025.06.04.657965

📫 Contact

For bug reports or feature requests, please open an issue on GitHub.