Metadata-Version: 2.4
Name: rdk-amber
Version: 0.1.0
Summary: Map AMBER/GAFF atom types to elements and load AMBER-style mol2 files into RDKit.
Author-email: Zeke Piskulich <piskulichz@gmail.com>
Maintainer-email: Zeke Piskulich <piskulichz@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/piskuliche/rdk-amber
Project-URL: Repository, https://github.com/piskuliche/rdk-amber
Project-URL: Issues, https://github.com/piskuliche/rdk-amber/issues
Keywords: rdkit,amber,gaff,mol2,cheminformatics,atom types
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rdkit
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Dynamic: license-file

# rdk-amber

Small utilities for bridging AMBER force-field conventions and RDKit:

1. A mapping between **AMBER / GAFF atom types** and chemical **elements**.
2. A loader that reads an **AMBER-style `mol2`** file (GAFF/AMBER atom types in
   the type column) into an `rdkit.Chem.Mol`.

RDKit's own `MolFromMol2File` expects *SYBYL* atom types (`C.3`, `N.ar`, …).
AmberTools (`antechamber`, `tleap`) instead writes GAFF/AMBER atom types
(`c3`, `na`, …) in that column, which RDKit cannot interpret. This package
parses such files directly.

## Install

```bash
pip install -e .
```

Requires `rdkit` (install via conda/pip).

## Usage

### Atom type → element

```python
from rdk_amber import element_from_amber_type

element_from_amber_type("c3")    # 'C'
element_from_amber_type("ho")    # 'H'
element_from_amber_type("Na+")   # 'Na'
element_from_amber_type("Xx")    # None  (unknown)
element_from_amber_type("Xx", strict=True)   # raises UnknownAtomTypeError
```

The full table is exposed as `rdk_amber.AMBER_ATOM_TYPE_TO_ELEMENT`. Types not
in the table fall back to a prefix heuristic (e.g. `c99 → C`).

### Load an AMBER mol2

```python
from rdk_amber import load_amber_mol2

mol = load_amber_mol2("ligand.mol2")          # sanitized RDKit Mol, with 3D coords
mol = load_amber_mol2("ligand.mol2", remove_hs=True)
```

Or use the class for more control / multi-molecule files:

```python
from rdk_amber import AmberMol2Loader

loader = AmberMol2Loader.from_file("ligand.mol2")
loader.num_molecules        # number of @<TRIPOS>MOLECULE records
loader.names                # their names
mol  = loader.to_rdkit(index=0, sanitize=True)
mols = loader.to_rdkit_all()
```

Each atom keeps the original AMBER data as properties:

| property | meaning |
| --- | --- |
| `_AmberAtomType` | the GAFF/AMBER atom type (`c3`, `ca`, …) |
| `_TriposAtomName` | the atom name column |
| `_TriposResidueName` | the substructure / residue name |
| `_TriposPartialCharge` | the mol2 partial charge (double) |

### Notes

- Bond orders are read from the `@<TRIPOS>BOND` section. `ar` → aromatic,
  `am` → single, `1/2/3` → single/double/triple.
- If sanitization fails (unusual force-field valences), pass `sanitize=False`
  to obtain the unsanitized molecule.
- Partial charges are stored as properties; formal charges are **not** inferred.

## Tests

```bash
pytest
```
# rdk-amber
