protonate-utils 0.1.0__py3-none-any.whl

protonate_utils-0.1.0.dist-info/METADATA

@@ -0,0 +1,294 @@
+Metadata-Version: 2.4
+Name: protonate-utils
+Version: 0.1.0
+Summary: Add hydrogens to ligands and proteins at a target pH.
+Author-email: Patrick Walters <wpwalters@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Patrick Walters
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/PatWalters/protonate_utils
+Project-URL: Repository, https://github.com/PatWalters/protonate_utils
+Project-URL: Issues, https://github.com/PatWalters/protonate_utils/issues
+Keywords: cheminformatics,protonation,hydrogens,rdkit,pdb
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rdkit
+Requires-Dist: dimorphite-dl
+Requires-Dist: biotite
+Requires-Dist: hydride
+Requires-Dist: numpy
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# protonate_utils
+
+A single utility for adding hydrogens to **ligands** and **proteins** at a
+target pH, for use in molecular modeling and structure-based drug design.
+
+## Why this exists
+
+Most structures you download — a ligand from a database, a protein from the
+PDB — are missing hydrogens, or carry hydrogens that don't reflect the
+protonation state at physiological pH. Getting these right matters: a
+carboxylic acid is deprotonated (`-COO⁻`) at pH 7.4, a basic amine is
+protonated (`-NH₃⁺`), and a histidine side chain can go either way. Downstream
+tasks — docking, free-energy calculations, MD simulations, electrostatics —
+all depend on the correct charge and hydrogen placement.
+
+Ligands and proteins need different tools for this. Small molecules are best
+handled with cheminformatics pKa models; proteins need residue-aware logic and
+geometry-based hydrogen placement. `protonate_utils.py` wraps the appropriate
+specialist tool for each case behind one consistent interface, so you don't
+have to remember two separate workflows:
+
+- **Ligands** use [Dimorphite-DL](https://github.com/durrantlab/dimorphite_dl)
+  for pH-aware protonation states and [the RDKit](https://www.rdkit.org/) for
+  structure handling. When the input has 3D coordinates, the heavy-atom
+  geometry is preserved exactly — only the newly added hydrogens are given
+  computed positions.
+- **Proteins** use [Hydride](https://hydride.biotite-python.org/) for
+  geometry-based hydrogen addition and
+  [Biotite](https://www.biotite-python.org/) for PDB handling, with formal
+  charges estimated per amino acid at the requested pH.
+
+Everything is exposed both as a **command-line tool** and as an importable
+**Python API**.
+
+## Installation
+
+Clone the repo and install it with `pip`:
+
+```bash
+git clone https://github.com/PatWalters/protonate_utils
+cd protonate_utils
+pip install -e .
+```
+
+This installs the dependencies for both modes (RDKit + Dimorphite-DL for
+ligands, Biotite + Hydride + NumPy for proteins), puts a `protonate-utils`
+command on your `PATH`, and makes `import protonate_utils` available.
+
+## Command-line usage
+
+Once installed, use the `protonate-utils` command. The first argument selects
+the mode: `ligand` or `protein`. (You can also run it without installing via
+`python protonate_utils.py …` from a checkout.)
+
+### Ligands
+
+```bash
+# SDF in, SDF out (3D coordinates preserved, hydrogens placed from geometry)
+protonate-utils ligand input.sdf output.sdf
+
+# SMILES in, SMILES out, at a custom pH
+protonate-utils ligand input.smi output.smi --ph 7.4
+
+# Mixed: read SDF, write SMILES
+protonate-utils ligand input.sdf output.smi
+```
+
+Input and output formats are inferred from the file extension:
+`.smi`/`.smiles` is treated as SMILES, anything else as SDF. SMILES files are
+read one molecule per line as `SMILES [optional name]`.
+
+| Option   | Default | Description                          |
+|----------|---------|--------------------------------------|
+| `--ph`   | `7.4`   | Target pH for protonation.           |
+
+Molecules that fail to parse or protonate are skipped with a warning on
+stderr; the run reports how many were read, written, and skipped.
+
+### Proteins
+
+```bash
+# Remove a bound ligand by residue name, then add hydrogens
+protonate-utils protein input.pdb AP5 output.pdb
+
+# Keep everything (no ligand removal)
+protonate-utils protein input.pdb none output.pdb --ph 7.0
+```
+
+The second positional argument is the residue name (3-letter CCD code) of a
+ligand to remove before protonation — pass `none` to keep all atoms. Output
+hydrogens are reordered so each one immediately follows the heavy atom it is
+bonded to.
+
+| Option       | Default | Description                                         |
+|--------------|---------|-----------------------------------------------------|
+| `--ph`       | `7.0`   | pH used to estimate amino-acid formal charges.      |
+| `--no-relax` | off     | Skip dihedral relaxation of the added hydrogens.    |
+
+## Python API
+
+Import the functions directly from `protonate_utils`. There are symmetric
+in-memory and file-to-file entry points for both ligands and proteins.
+
+|                  | Ligands                                  | Proteins                          |
+|------------------|------------------------------------------|-----------------------------------|
+| In-memory core   | `protonate_molecule(mol, ph)`            | `protonate_structure(structure, …)` |
+| Convenience      | `protonate_smiles_string(smiles, ph)`    | —                                 |
+| File → file      | `protonate_ligands(in, out, ph)`         | `prepare_structure(in, res, out, …)` |
+| I/O helpers      | `read_molecules(path)`, `make_writer(path)` | (Biotite `PDBFile`)            |
+
+### Ligands
+
+Protonate a single SMILES string and get a SMILES string back:
+
+```python
+from protonate_utils import protonate_smiles_string
+
+protonate_smiles_string("CC(=O)O")             # 'CC(=O)[O-]'
+protonate_smiles_string("OP(=O)(O)O", ph=7.4)  # 'O=P([O-])([O-])O'
+```
+
+`protonate_smiles_string` raises `ValueError` on an unparseable SMILES; other
+failures (e.g. Dimorphite-DL cannot handle the molecule) propagate as
+exceptions.
+
+Protonate an RDKit `Mol` while preserving its 3D coordinates:
+
+```python
+from rdkit import Chem
+from protonate_utils import protonate_molecule, read_molecules
+
+mol = next(read_molecules("ligand.sdf"))
+protonated = protonate_molecule(mol, ph=7.4)   # Mol with explicit Hs + coords
+```
+
+Pass `add_coord_hs=False` to keep protonation implicit (no explicit hydrogen
+atoms added) — appropriate when you intend to serialize to SMILES.
+
+Batch-convert a whole file (the CLI ligand path):
+
+```python
+from protonate_utils import protonate_ligands
+
+protonate_ligands("input.sdf", "output.sdf", ph=7.4)
+```
+
+### Proteins
+
+Protonate an in-memory Biotite `AtomArray` and get a hydrogenated one back:
+
+```python
+import biotite.structure.io.pdb as pdb
+from protonate_utils import protonate_structure
+
+structure = pdb.PDBFile.read("input.pdb").get_structure(model=1)
+hydrogenated = protonate_structure(
+    structure,
+    ligand_res_name="AP5",   # or None / "none" to keep all atoms
+    ph=7.0,
+    relax=True,
+)
+```
+
+`protonate_structure` raises `ValueError` if `ligand_res_name` is given but no
+atoms with that residue name exist. The returned `AtomArray` has hydrogens
+added and reordered to follow their bonded heavy atoms.
+
+Read a PDB, protonate, and write a PDB in one call (the CLI protein path):
+
+```python
+from protonate_utils import prepare_structure
+
+prepare_structure("input.pdb", "AP5", "output.pdb", ph=7.0, relax=True)
+```
+
+## How it works
+
+### Ligand protonation
+
+1. Pre-existing hydrogens are stripped; any 3D conformer on the heavy atoms is
+   kept.
+2. Dimorphite-DL enumerates candidate microstate(s) within a ±0.5 pH window.
+   One is chosen deterministically by a **site-by-site plausibility** check
+   rather than by net charge — see
+   [Correcting Dimorphite-DL microstates](#correcting-dimorphite-dl-microstates)
+   below — and any residual implausible ionization is repaired against the
+   input. The SMILES string is a final tiebreak, so re-runs are stable.
+3. The chosen template's formal charges **and** total hydrogen counts are
+   mapped back onto the original atoms via a charge-insensitive substructure
+   match (so `-COOH` still matches `-COO⁻`). Carrying the H count — not just
+   the charge — keeps the RDKit's kekulization correct on aromatic heterocycles.
+4. With 3D input, `Chem.AddHs(addCoords=True)` adds hydrogens positioned from
+   the existing geometry; heavy-atom coordinates are never moved. Without
+   coordinates (SMILES), protonation stays implicit.
+
+### Correcting Dimorphite-DL microstates
+
+Dimorphite-DL enumerates *every* microstate whose modeled pKa falls anywhere
+near the pH window, including many that are negligibly populated at pH 7.4. Left
+to a "most ionized" or "closest net charge" rule, the selector picks chemically
+wrong states: it deprotonates amides and phenols and protonates anilines. We add
+a per-atom legitimacy check (`_charge_change_is_legitimate`) that compares each
+candidate to the input atom-by-atom and accepts a formal-charge change only when
+that group genuinely ionizes near physiological pH:
+
+| Group | Typical pKa | At pH 7.4 | Dimorphite enumerates | We |
+|-------|-------------|-----------|-----------------------|----|
+| Aliphatic amine | pKaH ~10 | cation | both | **protonate** |
+| Amidine / guanidine | pKaH ~12–13 | cation | both | **protonate** |
+| Carboxylic acid | ~4 | anion | anion | **deprotonate** |
+| Sulfonic / sulfinic / phosphate / phosphonate | <2–7 | anion | anion | **deprotonate** |
+| Sulfonamide / acylsulfonamide / tetrazole | ~3–10 | anion | both | **deprotonate** |
+| Carboxamide N–H | ~17–22 | neutral | both → `[N⁻]` *or* `[NH⁺]` | **keep neutral** |
+| Aniline / amino-heteroarene | pKaH ~3–5 | neutral | both → `[NH⁺]` | **keep neutral** |
+| Cyanamide (N–C≡N) | pKaH ~0 | neutral | both → `[NH⁺]` | **keep neutral** |
+| Imidazole / pyrazole / indazole / indole / triazole N–H | ~10–17 | neutral | both → `[n⁻]` | **keep neutral** |
+| Phenol / alcohol | ~10–16 | neutral | both → `[O⁻]` | **keep neutral** |
+| Plain thiol / thione | ~7–10 | neutral | both → `[S⁻]` | **keep neutral** |
+
+Two further safeguards:
+
+- **Repair fallback.** When Dimorphite offers *only* an implausibly-ionized
+  microstate (e.g. it returns just the `[N⁻]` form of an O-alkyl hydroxamate or
+  imide, with no neutral alternative to select), the offending site is reverted
+  to the input's protonation rather than emitted as-is.
+- **Input charges preserved.** A change is only judged relative to the input, so
+  charges already present in the SMILES — quaternary ammonium salts, *N*-oxides,
+  mesoionic zwitterions — are never altered.
+
+Borderline acids/bases whose pKa sits right at 7.4 (e.g. *p*-nitrophenol ~7.15,
+mercaptoazoles ~7) are deliberately defaulted to neutral; they are ~50/50 at
+physiological pH, so this is at least as defensible as ionizing them and avoids
+mis-ionizing the far more common ordinary phenols and amides. Validated across
+the 2,173-molecule Biogen logS set: no skips, no heavy-atom changes, and the
+selection is deterministic.
+
+### Protein protonation
+
+1. Optionally remove a ligand by residue name, then strip any existing
+   hydrogens.
+2. Assign covalent bonds from CCD residue templates
+   (`connect_via_residue_names`).
+3. Estimate per-residue formal charges for canonical amino acids at the
+   requested pH (`hydride.estimate_amino_acid_charges`).
+4. Add hydrogens with Hydride and, by default, relax their geometry.
+5. Reorder atoms so each hydrogen immediately follows the heavy atom it is
+   bonded to.

protonate_utils-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+protonate_utils.py,sha256=eBk8YVXQa4_6D32sewXyBJJ-hVfwh3DqdHoho4PQuos,32105
+protonate_utils-0.1.0.dist-info/licenses/LICENSE,sha256=Qavx6RZFwj7qFjJ2V7LUMTeuYsOV9p5yXL1E8xf7WMg,1072
+protonate_utils-0.1.0.dist-info/METADATA,sha256=TKGgIP0wlAb1l1mmGUVMai2DrV4XDc-61EENk29wGAY,12948
+protonate_utils-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+protonate_utils-0.1.0.dist-info/entry_points.txt,sha256=je5fmMyHIYDcSYTnlcmFQyiORt-4C37WEPQAdHlzwfk,57
+protonate_utils-0.1.0.dist-info/top_level.txt,sha256=5AXq8us0pha4ORS_L-5DdMpziL307cpPjLt-8AqiSZk,16
+protonate_utils-0.1.0.dist-info/RECORD,,

protonate_utils-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

protonate_utils-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+protonate-utils = protonate_utils:main

protonate_utils-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Walters
+
+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.

protonate_utils-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+protonate_utils

protonate_utils.py

@@ -0,0 +1,827 @@
+#!/usr/bin/env python
+"""
+Protonation utilities for both ligands and proteins, selected by the
+first command-line argument:
+
+    protonate_utils.py ligand  ...    # small molecules (SDF/SMILES)
+    protonate_utils.py protein ...    # protein structures (PDB)
+
+Ligand mode
+-----------
+Add hydrogens to small molecules at a target pH (default 7.4). Input and
+output may be either SDF or SMILES; the format is inferred from the file
+extension (.smi/.smiles for SMILES, otherwise SDF).
+
+pH-aware protonation states are predicted with Dimorphite-DL, the
+resulting formal charges *and* H counts are mapped back onto the
+original molecule via substructure matching, and explicit hydrogens are
+added with Chem.AddHs(addCoords=True). When the input has 3D coordinates
+(SDF), heavy-atom positions are not disturbed; only the newly added
+hydrogens get computed positions based on the existing geometry. SMILES
+input has no coordinates, so protonation is applied without any geometry.
+
+Protein mode
+------------
+Read a local PDB file, optionally remove a ligand by residue name, add
+hydrogens with Hydride at a target pH (default 7.0), and write the
+result to a PDB file. Hydrogens are reordered so that each hydrogen
+immediately follows the heavy atom to which it is bonded.
+
+Install:
+    pip install rdkit dimorphite-dl          # ligand mode
+    pip install biotite hydride numpy        # protein mode
+
+Usage:
+    protonate_utils.py ligand input.sdf output.sdf
+    protonate_utils.py ligand input.smi output.smi --ph 7.4
+    protonate_utils.py protein input.pdb AP5 output.pdb
+    protonate_utils.py protein input.pdb none output.pdb --ph 7.0
+"""
+
+import argparse
+import sys
+
+
+# ---------------------------------------------------------------------------
+# Ligand mode (RDKit + Dimorphite-DL)
+# ---------------------------------------------------------------------------
+
+def _skeleton_copy(mol):
+    """
+    Return a charge- and H-agnostic copy of `mol` for use as a
+    substructure-match template that aligns two molecules differing only in
+    protonation state (an input molecule against a Dimorphite-DL microstate of
+    itself).
+
+    Bond orders and aromaticity are preserved -- they are what distinguishes,
+    say, an amidine's ``=N`` from its ``-N``, so flattening them would let the
+    charge/H mapping land on the wrong nitrogen and blow up its valence.
+    Only formal charges, explicit Hs and radicals are cleared, and implicit
+    Hs are switched off so a neutralized cation can't overflow its valence.
+
+    Crucially we do *not* run a full sanitize: re-kekulizing a neutralized
+    aromatic cation such as a protonated pyridinium ``[nH+]`` is what made the
+    indazole/imidazole molecules fail. The molecule keeps the aromaticity
+    perceived at parse time, and a light property-cache/ring refresh is all
+    substructure matching needs, so this never raises.
+    """
+    from rdkit import Chem
+
+    m = Chem.RWMol(mol)
+    for a in m.GetAtoms():
+        a.SetFormalCharge(0)
+        a.SetNumExplicitHs(0)
+        a.SetNoImplicit(True)
+        a.SetNumRadicalElectrons(0)
+    m.UpdatePropertyCache(strict=False)
+    Chem.FastFindRings(m)
+    return m
+
+
+def _is_amide_nitrogen(n_atom):
+    """
+    True if `n_atom` is a (thio)carboxamide nitrogen -- bonded to a carbon
+    that bears a double bond to O or S -- and *not* also bonded to a sulfonyl
+    group. A plain carboxamide N-H has pKa ~17-22 and stays neutral at
+    physiological pH, but an (acyl)sulfonamide N-H is genuinely acidic, so we
+    exclude that case (the caller treats its deprotonation as legitimate).
+    """
+    from rdkit import Chem
+
+    has_carbonyl = False
+    has_sulfonyl = False
+    for nbr in n_atom.GetNeighbors():
+        z = nbr.GetAtomicNum()
+        if z == 6:
+            for b in nbr.GetBonds():
+                other = b.GetOtherAtom(nbr)
+                if (b.GetBondType() == Chem.BondType.DOUBLE
+                        and other.GetAtomicNum() in (8, 16)):
+                    has_carbonyl = True
+        elif z == 16:
+            # Sulfonyl S(=O)(=O) neighbour -> acidic (acyl)sulfonamide.
+            o_doubles = sum(
+                1 for b in nbr.GetBonds()
+                if b.GetBondType() == Chem.BondType.DOUBLE
+                and b.GetOtherAtom(nbr).GetAtomicNum() == 8
+            )
+            if o_doubles >= 2:
+                has_sulfonyl = True
+    return has_carbonyl and not has_sulfonyl
+
+
+def _nitrogen_is_acylated_or_sulfonylated(n_atom):
+    """
+    True if `n_atom` is bonded to a carbonyl/thiocarbonyl carbon or a sulfonyl
+    sulfur. Such a nitrogen (amide, imide, sulfonamide, N-acylsulfonamide) has
+    its lone pair tied up by the adjacent electron-withdrawing group and is not
+    basic, so it must never be *protonated* at physiological pH -- even the
+    acidic acylsulfonamide/imide cases, which `_is_amide_nitrogen` deliberately
+    excludes so their *deprotonation* stays allowed.
+    """
+    from rdkit import Chem
+
+    for nbr in n_atom.GetNeighbors():
+        z = nbr.GetAtomicNum()
+        if z == 6:
+            for b in nbr.GetBonds():
+                other = b.GetOtherAtom(nbr)
+                if (b.GetBondType() == Chem.BondType.DOUBLE
+                        and other.GetAtomicNum() in (8, 16)):
+                    return True
+        elif z == 16:
+            o_doubles = sum(
+                1 for b in nbr.GetBonds()
+                if b.GetBondType() == Chem.BondType.DOUBLE
+                and b.GetOtherAtom(nbr).GetAtomicNum() == 8
+            )
+            if o_doubles >= 2:
+                return True
+    return False
+
+
+def _is_aromatic_amine_nitrogen(n_atom):
+    """
+    True if `n_atom` is an aniline/aromatic-amine nitrogen -- a non-aromatic N
+    bonded directly to an aromatic ring atom -- whose lone pair is delocalised
+    into the ring. Such nitrogens are weak bases (aniline pKaH ~4.6;
+    amino-pyridines/-pyrimidines/-azines pKaH ~3-5) and stay essentially neutral
+    at pH 7.4, yet Dimorphite-DL still enumerates a protonated microstate for
+    them.
+
+    An *aliphatic* amine (no aromatic neighbour) and the C=N nitrogens of an
+    amidine/guanidine/benzamidine (whose neighbouring carbon is not itself
+    aromatic) are excluded here, so they remain protonatable. Strongly-basic
+    amino-heteroarenes (e.g. 2-aminoimidazole, 4-aminopyridine) protonate on
+    their *ring* nitrogen, a different atom, so this exclusion does not affect
+    them.
+    """
+    if n_atom.GetAtomicNum() != 7 or n_atom.GetIsAromatic():
+        return False
+    if _is_amide_nitrogen(n_atom):
+        return False
+    return any(nbr.GetIsAromatic() for nbr in n_atom.GetNeighbors())
+
+
+def _is_cyanamide_nitrogen(n_atom):
+    """
+    True if `n_atom` is a cyanamide nitrogen -- bonded to a nitrile carbon
+    (N-C#N). The triple-bonded nitrile is strongly electron-withdrawing and
+    ties up the nitrogen lone pair, so a dialkylcyanamide has pKaH ~0 (cyanamide
+    itself is faintly *acidic*, pKa ~10) and is non-basic at pH 7.4. Dimorphite-DL
+    nonetheless enumerates a protonated microstate for it, which we must reject.
+    """
+    from rdkit import Chem
+
+    if n_atom.GetAtomicNum() != 7:
+        return False
+    for nbr in n_atom.GetNeighbors():
+        if nbr.GetAtomicNum() != 6:
+            continue
+        for b in nbr.GetBonds():
+            other = b.GetOtherAtom(nbr)
+            if (b.GetBondType() == Chem.BondType.TRIPLE
+                    and other.GetAtomicNum() == 7
+                    and other.GetIdx() != n_atom.GetIdx()):
+                return True
+    return False
+
+
+def _bonded_to_acidifying_centre(atom):
+    """
+    True if `atom` is bonded to an electron-withdrawing centre that makes an
+    O-H/S-H on it a strong acid (pKa < ~7): a carbonyl/thiocarbonyl carbon
+    (carboxyl/thioacid), a phosphorus oxyacid, or a sulfur oxyacid. Used to
+    tell a genuine acid (carboxyl pKa ~4, sulfonic <2, phosphate ~1-7) apart
+    from a weak one whose conjugate base is essentially absent at pH 7.4.
+    """
+    from rdkit import Chem
+
+    for nbr in atom.GetNeighbors():
+        z = nbr.GetAtomicNum()
+        if z in (15, 16):
+            # Phosphorus oxyacid, or sulfonic/sulfinic acid: the neighbouring
+            # P/S bears at least one double-bonded oxygen.
+            if any(
+                b.GetBondType() == Chem.BondType.DOUBLE
+                and b.GetOtherAtom(nbr).GetAtomicNum() == 8
+                for b in nbr.GetBonds()
+            ):
+                return True
+        elif z == 6:
+            # Carbonyl/thiocarbonyl carbon -> carboxyl / thioacid.
+            for b in nbr.GetBonds():
+                other = b.GetOtherAtom(nbr)
+                if (b.GetBondType() == Chem.BondType.DOUBLE
+                        and other is not atom
+                        and other.GetAtomicNum() in (8, 16)):
+                    return True
+    return False
+
+
+def _is_acidic_oxygen(o_atom):
+    """
+    True if deprotonating this oxygen's O-H gives an anion that actually exists
+    at pH 7.4 -- i.e. the oxygen of a carboxyl, sulfonic/sulfinic, or
+    phosphorus oxyacid (pKa < ~7). A phenol (O on an aromatic carbon, pKa ~10),
+    an alcohol (O on sp3 carbon, pKa ~16), or a hydroxy-heteroarene (really a
+    neutral lactam tautomer) is >90% neutral at physiological pH, yet
+    Dimorphite-DL still enumerates its ``[O-]`` microstate, so those must be
+    rejected -- the acid-side analogue of the weak amide/azole N-H.
+    """
+    return o_atom.GetAtomicNum() == 8 and _bonded_to_acidifying_centre(o_atom)
+
+
+def _is_acidic_sulfur(s_atom):
+    """
+    True if deprotonating this sulfur's S-H gives a thiolate present at pH 7.4
+    -- a thioacid S adjacent to a carbonyl (pKa ~3) or a sulfur/phosphorus
+    oxyacid. A plain alkyl thiol (pKa ~10.5) or aromatic thiol/thione (pKa ~7,
+    e.g. a mercaptoazole) is predominantly neutral, so its Dimorphite-enumerated
+    ``[S-]`` microstate is rejected.
+    """
+    return s_atom.GetAtomicNum() == 16 and _bonded_to_acidifying_centre(s_atom)
+
+
+def _is_acidic_aromatic_nitrogen(n_atom):
+    """
+    True if `n_atom` is an aromatic ring N-H acidic enough to deprotonate near
+    physiological pH. In practice that means only tetrazole-grade azoles,
+    whose ring carries four nitrogens (N-H pKa ~4.9). The common aromatic
+    N-H heterocycles -- pyrrole/indole (1 ring N, pKa ~17), imidazole/pyrazole
+    (2 N, pKa ~14), triazole (3 N, pKa ~10) -- are >99% neutral at pH 7.4, so
+    their Dimorphite-enumerated ``[n-]`` microstates must be rejected.
+    """
+    mol = n_atom.GetOwningMol()
+    ring_info = mol.GetRingInfo()
+    idx = n_atom.GetIdx()
+    most_ring_nitrogens = 0
+    for ring in ring_info.AtomRings():
+        if idx in ring:
+            n_count = sum(
+                1 for i in ring if mol.GetAtomWithIdx(i).GetAtomicNum() == 7
+            )
+            most_ring_nitrogens = max(most_ring_nitrogens, n_count)
+    return most_ring_nitrogens >= 4
+
+
+def _charge_change_is_legitimate(atom, delta_q):
+    """
+    Decide whether changing `atom`'s formal charge by `delta_q` (candidate
+    minus input) reflects a real ionization near physiological pH.
+
+    Protonation to a cation is only sensible on a nitrogen base (amine,
+    amidine, guanidine, aromatic N). Deprotonation to an anion is sensible on a
+    strong oxygen/sulfur acid (carboxyl, sulfonic/sulfinic, phosphate, thioacid)
+    and on a genuinely acidic nitrogen (sulfonamide, tetrazole, ...). It is
+    *not* sensible on the weakly-acidic groups that Dimorphite-DL nonetheless
+    enumerates a deprotonated microstate for: a plain carboxamide (pKa ~17-22)
+    or aromatic N-H heterocycle (imidazole/pyrazole/indazole/indole, pKa
+    ~13-17), nor a phenol (pKa ~10), alcohol (pKa ~16), or plain thiol/thione
+    (pKa ~7-10), all >90% neutral at pH 7.4. Flagging those here lets the
+    selector reject them.
+    """
+    if delta_q > 0:
+        # Protonation to a cation. Only a nitrogen base accepts a proton near
+        # physiological pH. An amide nitrogen is *not* basic (its conjugate
+        # acid pKa is ~0), so reject protonation there even though Dimorphite-DL
+        # enumerates the [NH+] microstate.
+        if atom.GetAtomicNum() != 7:
+            return False
+        if _nitrogen_is_acylated_or_sulfonylated(atom):
+            return False
+        if _is_aromatic_amine_nitrogen(atom):
+            return False
+        if _is_cyanamide_nitrogen(atom):
+            return False
+        return True
+    # delta_q < 0: deprotonation to an anion.
+    z = atom.GetAtomicNum()
+    if z == 8:
+        # Carboxyl/sulfonate/phosphate oxygen deprotonates; phenol/alcohol
+        # (pKa ~10-16) stays neutral at pH 7.4.
+        return _is_acidic_oxygen(atom)
+    if z == 16:
+        # Thioacid sulfur deprotonates; plain thiol/thione stays neutral.
+        return _is_acidic_sulfur(atom)
+    if z == 7:
+        if _is_amide_nitrogen(atom):
+            return False
+        if atom.GetIsAromatic() and not _is_acidic_aromatic_nitrogen(atom):
+            return False
+        return True
+    return False
+
+
+def _count_illegitimate_ionizations(input_mol, cand_mol):
+    """
+    Align `cand_mol` to `input_mol` atom-by-atom -- their heavy-atom
+    skeletons are identical, only protonation differs -- and count the formal
+    charge changes that don't correspond to a legitimate ionization (see
+    `_charge_change_is_legitimate`). Comparing against the input (rather than
+    against neutral) means a charge already present in the input is never
+    penalised; only newly introduced, chemically implausible ionizations are.
+
+    Returns a large sentinel if the two can't be aligned, so such candidates
+    sort last without crashing the selection.
+    """
+    match = _skeleton_copy(input_mol).GetSubstructMatch(
+        _skeleton_copy(cand_mol)
+    )
+    if not match or len(match) != cand_mol.GetNumAtoms():
+        return 1_000_000
+
+    bad = 0
+    for cand_idx, input_idx in enumerate(match):
+        ca = cand_mol.GetAtomWithIdx(cand_idx)
+        ia = input_mol.GetAtomWithIdx(input_idx)
+        delta_q = ca.GetFormalCharge() - ia.GetFormalCharge()
+        if delta_q and not _charge_change_is_legitimate(ca, delta_q):
+            bad += 1
+    return bad
+
+
+def _repair_illegitimate_ionizations(input_mol, cand_smiles):
+    """
+    Revert any still-illegitimate ionization in `cand_smiles` to the input's
+    protonation at that atom.
+
+    Selection (`_pick_state`) can only choose among the microstates
+    Dimorphite-DL offers. For an activated-but-not-acidic nitrogen -- an
+    O-alkyl hydroxamate, an acylhydrazide, a plain imide -- Dimorphite may
+    return *only* the deprotonated ``[N-]`` form, with no neutral alternative
+    to pick. Here we align the chosen candidate to the input atom-by-atom and,
+    for every formal-charge change that isn't a legitimate ionization (see
+    `_charge_change_is_legitimate`), copy the input atom's charge and hydrogen
+    count back onto the candidate. Genuine acids handled correctly upstream
+    (carboxyl, sulfonamide, tetrazole, acylsulfonamide) have *legitimate*
+    changes and are left untouched.
+
+    Returns a canonical SMILES, or `cand_smiles` unchanged if the molecules
+    can't be aligned or the repaired structure won't sanitize.
+    """
+    from rdkit import Chem
+
+    if input_mol is None:
+        return cand_smiles
+    cand_mol = Chem.MolFromSmiles(cand_smiles)
+    if cand_mol is None:
+        return cand_smiles
+
+    match = _skeleton_copy(input_mol).GetSubstructMatch(_skeleton_copy(cand_mol))
+    if not match or len(match) != cand_mol.GetNumAtoms():
+        return cand_smiles
+
+    rw = Chem.RWMol(cand_mol)
+    changed = False
+    for cand_idx, input_idx in enumerate(match):
+        ca = rw.GetAtomWithIdx(cand_idx)
+        ia = input_mol.GetAtomWithIdx(input_idx)
+        delta_q = ca.GetFormalCharge() - ia.GetFormalCharge()
+        if delta_q and not _charge_change_is_legitimate(ca, delta_q):
+            ca.SetFormalCharge(ia.GetFormalCharge())
+            ca.SetNumExplicitHs(ia.GetTotalNumHs())
+            ca.SetNoImplicit(True)
+            changed = True
+
+    if not changed:
+        return cand_smiles
+    try:
+        repaired = rw.GetMol()
+        Chem.SanitizeMol(repaired)
+    except Exception:
+        return cand_smiles
+    return Chem.MolToSmiles(repaired)
+
+
+def _pick_state(input_smiles, states):
+    """
+    Choose one microstate from Dimorphite-DL's output deterministically.
+
+    Dimorphite returns every microstate whose pKa falls within the
+    requested pH window. Its list order is not stable across Python
+    runs, so taking `states[0]` makes the pipeline non-deterministic:
+    e.g. a secondary alkyl amide can come back as either NH or N-, and
+    we'd silently flip between them on re-runs.
+
+    Selection happens in two tiers (lower is better):
+
+    1. **Site-by-site plausibility.** Each candidate is aligned to the
+       input atom-by-atom and its formal-charge changes are checked: a
+       cation must form on a nitrogen base, an anion on an O/S acid or a
+       genuinely acidic nitrogen (sulfonamide, tetrazole, ...). Dimorphite
+       also enumerates implausible microstates -- most notably a
+       deprotonated carboxamide ``C(=O)[N-]`` (N-H pKa ~17-22) -- and those
+       are penalised by their count of illegitimate changes, so the neutral
+       amide is kept over its bogus anion.
+
+    2. **Most ionized.** Among equally plausible candidates, prefer the one
+       with the greatest total ionic character (sum of |formal charge|).
+       When dimorphite is unsure it returns both the ionized and the neutral
+       form (a primary amine comes back as both ``CCC[NH3+]`` and ``CCCN``);
+       this keeps the ionized one and, unlike "match the input charge", does
+       not collapse back to a neutral input drawn without explicit charges. A
+       zwitterion (net charge 0 but two charged atoms) is preferred over its
+       neutral form.
+
+    The SMILES string is a final deterministic tiebreak. For groups with
+    pKa far from the pH window dimorphite returns a single state, so the
+    choice only matters when dimorphite is unsure.
+    """
+    from rdkit import Chem
+
+    input_mol = Chem.MolFromSmiles(input_smiles)
+
+    def score(smi):
+        m = Chem.MolFromSmiles(smi)
+        if m is None:
+            # Unparseable candidate: sort strictly last.
+            return (1_000_000, 0, smi)
+        illegitimate = (
+            _count_illegitimate_ionizations(input_mol, m)
+            if input_mol is not None else 0
+        )
+        ionic = sum(abs(a.GetFormalCharge()) for a in m.GetAtoms())
+        # Fewest implausible ionizations first, then most ionized
+        # (negate for min), then SMILES tiebreak.
+        return (illegitimate, -ionic, smi)
+
+    best = min(states, key=score)
+    # The best available state may still carry an illegitimate ionization when
+    # Dimorphite offered no cleaner alternative; revert those sites to the input.
+    return _repair_illegitimate_ionizations(input_mol, best)
+
+
+def _target_atom_states(mol_heavy, ph):
+    """
+    Use Dimorphite-DL to determine the dominant protonation state at
+    `ph`, then return a dict {atom_idx: (formal_charge, total_num_hs)}
+    aligned to the atom indices of `mol_heavy`.
+
+    Returning the total H count along with the charge is important: for
+    aromatic heterocycles, charge alone underspecifies the atom and
+    RDKit will fail to kekulize after the change. The template's H count
+    fully constrains the bonding state.
+    """
+    from rdkit import Chem
+    from dimorphite_dl import protonate_smiles
+
+    smiles = Chem.MolToSmiles(mol_heavy)
+    states = protonate_smiles(smiles, ph_min=ph - 0.5, ph_max=ph + 0.5)
+    if not states:
+        raise RuntimeError(f"Dimorphite-DL returned no states for {smiles!r}")
+
+    chosen = _pick_state(smiles, states)
+    template = Chem.MolFromSmiles(chosen)
+    if template is None:
+        raise RuntimeError(
+            f"RDKit could not parse Dimorphite-DL output {chosen!r}"
+        )
+
+    # Map heavy-atom indices between original and template via a skeleton
+    # (charge/H/bond-order-agnostic) match, so e.g. -COOH still matches -COO-
+    # and protonated aromatic heterocycles still match their neutral form.
+    match = _skeleton_copy(mol_heavy).GetSubstructMatch(
+        _skeleton_copy(template)
+    )
+    if not match:
+        raise RuntimeError(
+            "Could not align protonation template with input molecule"
+        )
+
+    out = {}
+    for template_idx, orig_idx in enumerate(match):
+        ta = template.GetAtomWithIdx(template_idx)
+        out[orig_idx] = (ta.GetFormalCharge(), ta.GetTotalNumHs())
+    return out
+
+
+def protonate_molecule(mol, ph, add_coord_hs=True):
+    """
+    Return a Mol with pH-appropriate protonation.
+
+    When the input carries a 3D conformer and `add_coord_hs` is set,
+    explicit hydrogens are added and positioned from the existing
+    geometry while the heavy-atom coordinates are preserved (this is the
+    SDF-output path). Otherwise protonation is left implicit, which is
+    what a SMILES writer wants and avoids hydrogens at bogus positions.
+    """
+    from rdkit import Chem
+
+    props = mol.GetPropsAsDict()
+    name = mol.GetProp("_Name") if mol.HasProp("_Name") else ""
+
+    # Strip any pre-existing Hs; any conformer on heavy atoms is preserved.
+    mol_heavy = Chem.RemoveHs(mol)
+    has_coords = mol_heavy.GetNumConformers() > 0
+
+    # Apply Dimorphite-DL's pH-appropriate charges and H counts to the
+    # molecule. Setting NoImplicit=True with an explicit H count makes
+    # the atom state fully determined, which keeps kekulization happy on
+    # aromatic heterocycles.
+    new_states = _target_atom_states(mol_heavy, ph)
+    mol_heavy = Chem.RWMol(mol_heavy)
+    for idx, (charge, n_hs) in new_states.items():
+        a = mol_heavy.GetAtomWithIdx(idx)
+        a.SetFormalCharge(charge)
+        a.SetNumExplicitHs(n_hs)
+        a.SetNoImplicit(True)
+    Chem.SanitizeMol(mol_heavy)
+
+    # With 3D coordinates, add explicit hydrogens positioned from the
+    # existing heavy-atom geometry (heavy-atom coordinates are not
+    # modified). Without coordinates, or when the caller doesn't want
+    # them, keep the protonation implicit so a SMILES writer renders it
+    # cleanly without bogus zeroed positions.
+    if has_coords and add_coord_hs:
+        protonated = Chem.AddHs(mol_heavy, addCoords=True)
+    else:
+        protonated = mol_heavy
+
+    # Restore name and SDF tags.
+    if name:
+        protonated.SetProp("_Name", name)
+    for key, value in props.items():
+        protonated.SetProp(key, str(value))
+    return protonated
+
+
+def protonate_smiles_string(smiles, ph=7.4):
+    """
+    Protonate a single SMILES string at `ph` and return the resulting
+    SMILES. Convenience wrapper around `protonate_molecule` for the
+    common string-in/string-out case (no coordinates involved).
+
+    Raises ValueError if `smiles` cannot be parsed; other failures
+    (e.g. Dimorphite-DL could not handle the molecule) propagate from
+    `protonate_molecule`.
+    """
+    from rdkit import Chem
+
+    mol = Chem.MolFromSmiles(smiles)
+    if mol is None:
+        raise ValueError(f"Could not parse SMILES {smiles!r}")
+    protonated = protonate_molecule(mol, ph, add_coord_hs=False)
+    return Chem.MolToSmiles(protonated)
+
+
+def _is_smiles_path(path):
+    return path.lower().endswith((".smi", ".smiles"))
+
+
+def read_molecules(path):
+    """
+    Yield molecules from `path`, which may be SMILES (.smi/.smiles) or
+    SDF. Unparseable entries are yielded as None so callers can count
+    and report them. SMILES files are read as one molecule per line,
+    "SMILES [optional name]".
+    """
+    from rdkit import Chem
+
+    if _is_smiles_path(path):
+        with open(path) as fh:
+            for line in fh:
+                line = line.strip()
+                if not line:
+                    continue
+                parts = line.split(None, 1)
+                mol = Chem.MolFromSmiles(parts[0])
+                if mol is not None and len(parts) > 1:
+                    mol.SetProp("_Name", parts[1].strip())
+                yield mol
+    else:
+        for mol in Chem.SDMolSupplier(path, removeHs=False, sanitize=True):
+            yield mol
+
+
+def make_writer(path):
+    """Return an SDF or SMILES writer based on the output extension."""
+    from rdkit import Chem
+
+    if _is_smiles_path(path):
+        return Chem.SmilesWriter(path, includeHeader=False)
+    return Chem.SDWriter(path)
+
+
+def protonate_ligands(input_path, output_path, ph):
+    """Batch-protonate a ligand file (SDF/SMILES) into another."""
+    writer = make_writer(output_path)
+    # SMILES output never needs coordinate-bearing explicit hydrogens.
+    add_coord_hs = not _is_smiles_path(output_path)
+
+    n_in = n_out = n_fail = 0
+    for mol in read_molecules(input_path):
+        n_in += 1
+        if mol is None:
+            n_fail += 1
+            print(
+                f"[warn] skipping molecule {n_in}: RDKit failed to parse",
+                file=sys.stderr,
+            )
+            continue
+        try:
+            protonated = protonate_molecule(mol, ph, add_coord_hs=add_coord_hs)
+        except Exception as exc:
+            n_fail += 1
+            label = mol.GetProp("_Name") if mol.HasProp("_Name") else f"#{n_in}"
+            print(f"[warn] skipping {label}: {exc}", file=sys.stderr)
+            continue
+        writer.write(protonated)
+        n_out += 1
+
+    writer.close()
+    print(f"Read {n_in} molecules, wrote {n_out}, skipped {n_fail}.")
+
+
+# ---------------------------------------------------------------------------
+# Protein mode (Biotite + Hydride)
+# ---------------------------------------------------------------------------
+
+def reorder_hydrogens_after_heavy_atoms(atoms):
+    """
+    Return a new AtomArray where each hydrogen immediately follows the
+    heavy atom it is bonded to.
+
+    Hydrogens bonded to the same heavy atom appear in the order Hydride
+    originally placed them. Orphan hydrogens (no heavy-atom bond found)
+    are appended at the end as a fallback.
+
+    The input AtomArray must have a populated BondList.
+    """
+    import numpy as np
+
+    if atoms.bonds is None:
+        raise ValueError(
+            "AtomArray must have an associated BondList; "
+            "call connect_via_residue_names() before reordering."
+        )
+
+    # neighbors has shape (n_atoms, max_bonds); -1 entries are padding.
+    neighbors, _ = atoms.bonds.get_all_bonds()
+    is_hydrogen = atoms.element == "H"
+    n_atoms = len(atoms)
+
+    new_order = []
+    placed = np.zeros(n_atoms, dtype=bool)
+
+    for i in range(n_atoms):
+        if placed[i] or is_hydrogen[i]:
+            continue
+        # Place the heavy atom.
+        new_order.append(i)
+        placed[i] = True
+        # Then its bonded hydrogens, in their original relative order.
+        h_indices = sorted(
+            int(j) for j in neighbors[i]
+            if j >= 0 and is_hydrogen[j] and not placed[j]
+        )
+        for j in h_indices:
+            new_order.append(j)
+            placed[j] = True
+
+    # Any leftover atoms (e.g. unbonded hydrogens) go at the end.
+    for i in range(n_atoms):
+        if not placed[i]:
+            new_order.append(i)
+            placed[i] = True
+
+    return atoms[new_order]
+
+
+def protonate_structure(structure, ligand_res_name=None, ph=7.0, relax=True):
+    """
+    Return a hydrogenated copy of a protein `AtomArray`.
+
+    In-memory analogue of `protonate_molecule` for proteins: takes an
+    AtomArray (e.g. from ``pdb.PDBFile.read(path).get_structure(model=1)``)
+    and returns a new AtomArray with pH-appropriate hydrogens added and
+    each hydrogen reordered to immediately follow its bonded heavy atom.
+
+    If `ligand_res_name` is given (and not "none"), atoms with that
+    residue name are removed first; a ValueError is raised if no such
+    atoms exist. Any pre-existing hydrogens are stripped before Hydride
+    adds them back.
+    """
+    import numpy as np
+    import biotite.structure as struc
+    import hydride
+
+    # Optionally remove the ligand by residue name (3-letter CCD code).
+    # "none" (any case) means "keep everything".
+    if ligand_res_name is not None and ligand_res_name.lower() != "none":
+        target = ligand_res_name.upper()
+        keep_mask = np.char.upper(structure.res_name.astype(str)) != target
+        if keep_mask.all():
+            raise ValueError(
+                f"No atoms with res_name '{target}' found in structure."
+            )
+        structure = structure[keep_mask]
+
+    # Strip any pre-existing hydrogens; Hydride will add them itself.
+    structure = structure[structure.element != "H"]
+
+    # Assign covalent bonds from CCD residue templates.
+    structure.bonds = struc.connect_via_residue_names(structure)
+
+    # Set formal charges for canonical amino acids at the requested pH.
+    charges = hydride.estimate_amino_acid_charges(structure, ph=ph)
+    structure.set_annotation("charge", charges)
+
+    # Add hydrogens, then optionally relax their geometry.
+    structure, _ = hydride.add_hydrogen(structure)
+    if relax:
+        structure.coord = hydride.relax_hydrogen(structure)
+
+    # Reorder so each hydrogen follows its bonded heavy atom.
+    return reorder_hydrogens_after_heavy_atoms(structure)
+
+
+def prepare_structure(input_path, ligand_res_name, output_path,
+                      ph=7.0, relax=True, quiet=False):
+    """
+    Read a PDB file, protonate it with `protonate_structure`, and write
+    the result to another PDB file. File-to-file driver analogous to
+    `protonate_ligands` on the ligand side.
+    """
+    import biotite.structure.io.pdb as pdb
+
+    structure = pdb.PDBFile.read(input_path).get_structure(model=1)
+    structure = protonate_structure(
+        structure, ligand_res_name=ligand_res_name, ph=ph, relax=relax
+    )
+
+    out = pdb.PDBFile()
+    out.set_structure(structure)
+    out.write(output_path)
+    if not quiet:
+        print(f"Wrote hydrogenated structure to {output_path}")
+
+
+# ---------------------------------------------------------------------------
+# Command-line interface
+# ---------------------------------------------------------------------------
+
+def parse_args():
+    p = argparse.ArgumentParser(
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    sub = p.add_subparsers(dest="mode", required=True,
+                           metavar="{ligand,protein}")
+
+    lig = sub.add_parser(
+        "ligand",
+        help="Protonate small molecules (SDF/SMILES).",
+        description="Protonate small molecules with Dimorphite-DL.",
+    )
+    lig.add_argument(
+        "input", help="Path to the input file (SDF, or .smi/.smiles for SMILES)"
+    )
+    lig.add_argument(
+        "output", help="Path to the output file (SDF, or .smi/.smiles for SMILES)"
+    )
+    lig.add_argument(
+        "--ph", type=float, default=7.4,
+        help="Target pH for protonation (default: 7.4)",
+    )
+
+    prot = sub.add_parser(
+        "protein",
+        help="Protonate a protein structure (PDB).",
+        description="Add hydrogens to a protein with Hydride.",
+    )
+    prot.add_argument("input", help="Path to the input PDB file")
+    prot.add_argument(
+        "ligand_res_name",
+        help="Residue name of the ligand to remove (e.g. ATP, HEM, AP5). "
+             "Pass 'none' to skip ligand removal.",
+    )
+    prot.add_argument("output", help="Path to the output PDB file")
+    prot.add_argument(
+        "--ph", type=float, default=7.0,
+        help="pH used to estimate amino-acid formal charges (default: 7.0)",
+    )
+    prot.add_argument(
+        "--no-relax", action="store_true",
+        help="Skip dihedral relaxation of hydrogens.",
+    )
+
+    return p.parse_args()
+
+
+def main():
+    args = parse_args()
+    if args.mode == "ligand":
+        protonate_ligands(args.input, args.output, args.ph)
+    elif args.mode == "protein":
+        prepare_structure(
+            input_path=args.input,
+            ligand_res_name=args.ligand_res_name,
+            output_path=args.output,
+            ph=args.ph,
+            relax=not args.no_relax,
+        )
+
+
+if __name__ == "__main__":
+    main()