Metadata-Version: 2.4
Name: cgback
Version: 1.0.0
Summary: Deep learning tool for backmapping coarse-grained to all-atom
Project-URL: Repository, https://github.com/bondrewd/cgback
Author-email: Diego Ugarte <diego.ugarte@outlook.com>
License: MIT License
        
        Copyright (c) 2025 Diego Renato Ugarte La Torre
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10.0
Requires-Dist: numpy>=2.1.0
Requires-Dist: rich>=13.9.4
Requires-Dist: scipy>=1.15.0
Requires-Dist: torch>=2.5.0
Provides-Extra: openmm
Requires-Dist: openmm>=8.2.0; extra == 'openmm'
Provides-Extra: openmm-cuda12
Requires-Dist: openmm[cuda12]>=8.2.0; extra == 'openmm-cuda12'
Description-Content-Type: text/markdown

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