added method for templating residues from a Molecule object

Author: stefdoerr

AGENTS.md

@@ -116,6 +116,12 @@ mask = mol.resname == "NAG"
 mol.templateResidueFromSmiles(mask, smiles="CC(=O)NC1C(O)C(O)C(CO)OC1O", addHs=True)
 ```
 
+To template from a reference structure (e.g. an RCSB chemical-component CIF)
+instead of a SMILES string, use `templateResidueFromMolecule(mask, refmol,
+addHs=True)`.  It matches the residue to the reference by atom name (same
+heavy-atom names required) and copies the reference's bond orders and formal
+charges verbatim, so those must already be correct in `refmol`.
+
 ---
 
 ### Compute a per-frame projection

doc/source/explanation/molecule-data-model.md

@@ -26,7 +26,7 @@ of length `mol.numAtoms`. The most commonly used fields are:
 | `charge` | `float32` | Partial charge (populated by force-field tools) |
 | `masses` | `float32` | Atomic mass in Da |
 | `record` | `object` | PDB record type: `"ATOM"` or `"HETATM"` |
-| `formalcharge` | `int32` | Integer formal charge (populated by {py:func}`~moleculekit.tools.preparation.systemPrepare` and {py:meth}`~moleculekit.molecule.Molecule.templateResidueFromSmiles`) |
+| `formalcharge` | `int32` | Integer formal charge (populated by {py:func}`~moleculekit.tools.preparation.systemPrepare`, {py:meth}`~moleculekit.molecule.Molecule.templateResidueFromSmiles`, and {py:meth}`~moleculekit.molecule.Molecule.templateResidueFromMolecule`) |
 | `atomtype` | `object` | Force-field atom type (populated downstream) |
 
 Because these arrays are NumPy arrays you can inspect, compare, and manipulate

doc/source/explanation/system-preparation-pipeline.md

@@ -201,6 +201,19 @@ mol_out, specs = systemPrepare(mol)
 {py:func}`~moleculekit.tools.preparation.systemPrepare` calls {py:func}`~moleculekit.tools.nonstandard_residues.detectNonStandardResidues` internally, so it will pick
 up the ligand spec automatically.
 
+If you already have the residue as a reference structure with correct
+connectivity (e.g. an RCSB chemical-component CIF), use
+{py:meth}`~moleculekit.molecule.Molecule.templateResidueFromMolecule` instead of
+a SMILES string. It matches the residue to the reference by atom name (the two
+must share the same heavy-atom names) and copies the reference's bond orders and
+formal charges verbatim, so those must already be correct in the reference:
+
+```python
+ref = Molecule("LIG.cif")   # correct bonds, bond orders, and formal charges
+mol.templateResidueFromMolecule("resname LIG", ref, addHs=True)
+mol_out, specs = systemPrepare(mol)
+```
+
 ### mutateResidue before systemPrepare
 
 When you want to swap canonical residues (e.g. a point mutation), call

doc/source/how-to/convert-to-rdkit-and-openff.md

@@ -95,7 +95,7 @@ rdmol = mol.toRDKitMol(sanitize=False)   # sanitize=False for non-canonical resi
 
 ## Gotchas
 
-- Conversion needs explicit bonds. If `mol.bonds` is empty (plain PDB load), run {py:meth}`~moleculekit.molecule.Molecule.templateResidueFromSmiles` for non-canonical residues so the conversion gets correct bond orders, or pass `guessBonds=True` for a distance-based fallback.
+- Conversion needs explicit bonds. If `mol.bonds` is empty (plain PDB load), run {py:meth}`~moleculekit.molecule.Molecule.templateResidueFromSmiles` (or {py:meth}`~moleculekit.molecule.Molecule.templateResidueFromMolecule`, when you have a reference structure such as a CIF with correct bond orders and formal charges) for non-canonical residues so the conversion gets correct bond orders, or pass `guessBonds=True` for a distance-based fallback.
 - `sanitize=True` will raise on residues whose bonding or formal charges are inconsistent with chemical rules. For a freshly read PDB this often happens around metal centers and covalent ligands; template those residues first (see [Custom residues from SMILES](../tutorials/system-prep/03-custom-residues-from-smiles.md)).
 - Hydrogens must be present for stereochemistry / valence checks. Run {py:func}`~moleculekit.tools.preparation.systemPrepare` (or set explicit Hs via `templateResidueFromSmiles(..., addHs=True)`) before conversion.
 - `toOpenFFMolecule` requires `openff-toolkit` and `openff-units` installed.

doc/source/how-to/guess-bonds.md

@@ -29,7 +29,7 @@ assert mol.bonds.shape[0] > 0, "No bonds guessed — check coordinates and eleme
 
 ## Gotchas
 
-- `mol.guessBonds()` does not infer bond orders; every entry in `mol.bondtype` is `"un"` (unknown). When bond orders matter (e.g. for {py:meth}`~moleculekit.molecule.Molecule.toRDKitMol` conversion or SMILES output), template the relevant residues from SMILES with {py:meth}`~moleculekit.molecule.Molecule.templateResidueFromSmiles` instead.
+- `mol.guessBonds()` does not infer bond orders; every entry in `mol.bondtype` is `"un"` (unknown). When bond orders matter (e.g. for {py:meth}`~moleculekit.molecule.Molecule.toRDKitMol` conversion or SMILES output), template the relevant residues from SMILES with {py:meth}`~moleculekit.molecule.Molecule.templateResidueFromSmiles` instead, or from a reference {py:class}`~moleculekit.molecule.Molecule` (e.g. a CIF carrying correct bond orders and formal charges) with {py:meth}`~moleculekit.molecule.Molecule.templateResidueFromMolecule`.
 - Very close non-bonded atoms (e.g. crystal contacts, stacking interactions) can be incorrectly identified as bonded.
 - **Do not assign `mol.bonds = guess_bonds(mol)` directly.** Always use `mol.guessBonds()`, which updates `mol.bonds` and `mol.bondtype` together. See [The Molecule data model: Bonds](../explanation/molecule-data-model.md#bonds-bonds-and-bondtype) for why the two arrays must stay in lockstep.
 

doc/source/llms.txt

@@ -8,7 +8,7 @@
 - [Atom selection](tutorials/02-atom-selection.md): VMD syntax and mask-based fast path.
 - [System prep: basic protonation](tutorials/system-prep/01-basic-protonation.md): `systemPrepare` at chosen pH; the default 2-tuple `(mol_out, detect_specs)` return (3-tuple `(mol_out, detect_specs, details)` with `return_details=True`).
 - [System prep: non-standard residues](tutorials/system-prep/02-non-standard-residues.md): `detectNonStandardResidues` + `systemPrepare(detect_specs=...)`.
-- [System prep: custom residues from SMILES](tutorials/system-prep/03-custom-residues-from-smiles.md): `templateResidueFromSmiles` with `addHs=True`.
+- [System prep: custom residues from SMILES](tutorials/system-prep/03-custom-residues-from-smiles.md): `templateResidueFromSmiles` with `addHs=True`; `templateResidueFromMolecule` to template from a reference Molecule (e.g. a CIF) carrying correct bond orders and formal charges.
 - [System prep: mutation, gap closing, segmentation](tutorials/system-prep/04-mutation-gap-closing-segmentation.md): `mutateResidue`, `model_gaps`, `autoSegment`.
 
 ## How-to guides

doc/source/tutorials/system-prep/03-custom-residues-from-smiles.md

@@ -96,6 +96,17 @@ show3d(mol, representations=[{"sel": "resname HRG ALC OIC NLE '200'", "type": "b
 
 The per-resname atom counts after templating — each NCAA now carries heavy atoms + the hydrogens the SMILES specified.
 
+### Alternative: template from a reference Molecule
+
+If you already have the residue as a small reference structure that carries correct connectivity (for example an RCSB chemical-component CIF for the ligand), you can template from that {py:class}`~moleculekit.molecule.Molecule` instead of writing a SMILES string, using {py:meth}`~moleculekit.molecule.Molecule.templateResidueFromMolecule`:
+
+```python
+ref = Molecule("HRG.cif")   # reference carrying correct bonds, bond orders, and formal charges
+mol.templateResidueFromMolecule("resname HRG", ref, addHs=True)
+```
+
+The reference is matched to the residue by **atom name** (not by MCS, as with SMILES), so the two must share the same set of heavy-atom names and the reference's heavy-atom names must be unique. The bond orders and formal charges are copied straight from the reference: they must therefore already be correct in the template Molecule, because `templateResidueFromMolecule` transfers them verbatim and does not re-derive them. Everything else (`addHs`, `guessBonds`, automatic cross-residue bond handling, and per-copy templating) works exactly as in the SMILES variant.
+
 ## Step 4 — Run systemPrepare
 
 ```{code-cell} python
@@ -116,6 +127,7 @@ The five NCAAs all survive the preparation pipeline with their full heavy-atom t
 - It removes any hydrogens already on the matched residue and re-adds them from the SMILES (`addHs=True`), so the hydrogen pattern is deterministic — no manual pre-stripping needed.
 - One SMILES per residue type; the templater handles every copy automatically and trims terminal atoms (OXT, terminal NH) for mid-chain residues.
 - Cross-residue covalent bonds — peptide bonds, glycosidic bonds, isopeptide bonds — are detected automatically; the boundary atom's H count is corrected so it is not over-protonated.
+- {py:meth}`~moleculekit.molecule.Molecule.templateResidueFromMolecule` is the same operation with a reference {py:class}`~moleculekit.molecule.Molecule` (e.g. a CIF) as the template instead of a SMILES string. It matches by atom name rather than MCS and copies the reference's bond orders and formal charges verbatim, so those must already be correct in the reference.
 
 ## Next
 

moleculekit/molecule.py

@@ -3103,6 +3103,62 @@ def templateResidueFromSmiles(
             _logger=_logger,
         )
 
+    def templateResidueFromMolecule(
+        self,
+        sel: "str | np.ndarray",
+        refmol: "Molecule",
+        addHs: bool = False,
+        onlyOnAtoms: "str | np.ndarray | None" = None,
+        guessBonds: bool = False,
+        _logger=True,
+    ):
+        """Assign bonds, bond orders, formal charges and (optionally) hydrogens
+        to a residue from a reference Molecule template, matched by atom name.
+
+        Like :meth:`templateResidueFromSmiles`, but the template is a reference
+        Molecule (e.g. loaded from a CIF) that already carries bonds, bond
+        orders and formal charges. The selected residue's heavy atoms are
+        mapped onto the reference by NAME and the reference's bond orders and
+        formal charges are transferred verbatim, so they must already be
+        correct in the reference (this function does not re-derive them). The
+        reference is used only as a template and is never appended. The
+        molecule is mutated in place. The residue and reference must share the
+        same set of heavy-atom names.
+
+        Parameters
+        ----------
+        sel : str or np.ndarray
+            An atom selection string, a boolean mask, or an integer index array
+            of the residue(s) to template. May span multiple copies.
+        refmol : Molecule
+            The reference template. Its bonds, bond orders and formal charges
+            are copied onto the residue verbatim, so they must already be
+            correct; heavy-atom names must be unique and must match the
+            residue's.
+        addHs : bool
+            If True, add hydrogens after bond orders are transferred.
+        onlyOnAtoms : str or np.ndarray
+            Restrict which heavy atoms get hydrogens (only used with addHs).
+        guessBonds : bool
+            If True, distance-guess the residue's bonds before templating.
+
+        Examples
+        --------
+        >>> mol = Molecule("complex.pdb")  # doctest: +SKIP
+        >>> mol.templateResidueFromMolecule("resname LIG", Molecule("LIG.cif"), addHs=True, guessBonds=True)
+        """
+        from moleculekit.rdkittools import template_residue_from_molecule
+
+        template_residue_from_molecule(
+            mol=self,
+            sel=sel,
+            refmol=refmol,
+            addHs=addHs,
+            onlyOnAtoms=onlyOnAtoms,
+            guessBonds=guessBonds,
+            _logger=_logger,
+        )
+
     def extendResidueFromSmiles(
         self,
         sel: str | np.ndarray,