# 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:

```bash
pip install cgback
```

or using uv:

```bash
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**:
```bash
# using pip
pip install cgback --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**:
```bash
# using pip
pip install cgback --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**:
```bash
# using pip
pip install cgback --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**:
```bash
# using pip
pip install cgback --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**:
```bash
# using pip
pip install cgback --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:

```bash
# using pip
pip install 'cgback[openmm]'

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

For OpenMM with **CUDA 12** support:
```bash
# 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:

```bash
# using pip
pip install 'cgback[openmm]' --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:

```bash
# using pip
pip install 'cgback[openmm-cuda12]' --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:

```bash
cgback input.pdb
```

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

## 📚 Examples

Basic backmapping:

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

Backmapping using different output formats:

```bash
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:

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

Backmapping using different models:

```bash
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:

```bash
cgback input.pdb -v
```

Save intermediate files:

```bash
cgback input.pdb -k
```

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

```bash
cgback input.pdb -e
```

## 🧪 Advanced Usage

Generate different outputs with controlled random seeds:

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

Specify the number of diffusion steps manually:

```bash
cgback input.pdb -n 150
```

Change batch size for larger or smaller memory usage:

```bash
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):

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

Skip fixing atomic clashes during refinement:

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

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

```bash
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:

```bash
# 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:

```bash
# 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:

```bash
# 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 corresponding paper (coming soon).

## 📫 Contact

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