Cite a mancude parent's surplus saturation as added hydrogen

A mancude parent hydride supports a fixed number of indicated hydrogens --
purine's nine skeletal atoms and four double bonds leave exactly one, which
is why it is cited as 7H- or 9H-purine.  Saturating further positions, as a
2,6-dione does, is *added* hydrogen and takes a hydro prefix.  openclatura
instead emitted one indicated-hydrogen citation per saturated position, and
joined them as a single locant set: `1,7H-purine-2,6-dione`, which is not a
readable name -- OPSIN rejects it outright.

Three changes:

  * Carry the supported indicated-hydrogen count on the retained parent
    metadata, taken from the template that declares its own positions
    (1H-indole, 9H-xanthene) or else from the mancude double-bond count.

  * Move saturation beyond that count into a hydro operation, keeping the
    lowest locants indicated.  A hydro prefix saturates whole double bonds,
    so it can only absorb an even surplus; an odd one stays indicated, as
    `1H,9H-purin-6-one`, which is still readable.

  * Count a saturated ring nitrogen whether it holds the hydrogen or a
    substituent.  The positions are a property of the parent hydride, not of
    what occupies them: theophylline is
    1,3-dimethyl-3,7-dihydro-1H-purine-2,6-dione even though N1 and N3 are
    both methylated.

Xanthine, theophylline and caffeine now match the reference tool exactly,
and every name involved round-trips through OPSIN to its input.  The
caffeine test pinned `1,3,7-trimethylpurine-2,6-dione`; that name also
resolves to caffeine, so it was incomplete rather than wrong, and is
updated.

Two corpus names improve; both were already correct and remain so.  They
stop being confirmed only because the audit models neither multiple
indicated hydrogens nor added hydrogen yet.  zinc22 97.63% unchanged,
pubchem 96.33%, refutations unchanged at 27.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: AdrianM0

src/openclatura/additive.py

@@ -1,6 +1,7 @@
 """Explicit additive/replacement feature collection for selected parents."""
 
 from .assembly_parts import AssemblyParts, SubstituentItem
+from .locants import parse_locant
 from .molecule import Molecule
 from .name_operations import HydroOperation
 from .namer_config import INDICATED_H_RETAINED_NAMES
@@ -28,7 +29,16 @@ def add_indicated_hydrogens(mol: Molecule, parts: AssemblyParts, numbered_path:
         if metadata is not None and default_indicated_h and atom.is_carbon and locant not in default_indicated_h:
             continue
         if oxo_derivative:
-            if atom.explicit_h_count + atom.total_h_count <= 0:
+            # A ring nitrogen at a saturated position is a hydrogenated position
+            # of the parent hydride whether it holds the hydrogen or a
+            # substituent, so theophylline is
+            # 1,3-dimethyl-3,7-dihydro-1H-purine-2,6-dione: N1 and N3 count even
+            # though both are methylated.
+            ring_bond_order = sum(
+                bond.order for n in mol.get_neighbors(idx) if n in numbered_path and (bond := mol.get_bond(idx, n))
+            )
+            substituted_ring_nitrogen = atom.symbol == "N" and ring_bond_order == 2
+            if atom.explicit_h_count + atom.total_h_count <= 0 and not substituted_ring_nitrogen:
                 continue
             # Hydrogen introduced next to =O is implied by ``-one``/``-dione``
             # and must not become a new indicated-H locant.  Carbon is allowed
@@ -77,6 +87,28 @@ def add_indicated_hydrogens(mol: Molecule, parts: AssemblyParts, numbered_path:
         )
         return
 
+    # A mancude parent hydride supports a fixed number of indicated hydrogens.
+    # Saturated positions beyond that are *added* hydrogen and take a hydro
+    # prefix, so xanthine is 3,7-dihydro-1H-purine-2,6-dione rather than a run
+    # of indicated-H citations.  The lowest locants stay indicated.
+    # A hydro prefix saturates whole double bonds, so it can only absorb an even
+    # surplus.  An odd one stays as indicated hydrogen (1H,9H-purin-6-one),
+    # which is still a readable name.
+    supported = metadata.indicated_hydrogen_count if metadata is not None else len(candidates)
+    if metadata is not None and len(candidates) > supported and (len(candidates) - supported) % 2 == 0:
+        candidates.sort(key=lambda candidate: parse_locant(candidate[0]))
+        surplus = candidates[supported:]
+        candidates = candidates[:supported]
+        parts.hydro_operations.append(
+            HydroOperation(
+                key="additive_hydrogen",
+                reason="Saturation beyond the parent's indicated hydrogen is added hydrogen.",
+                locants=tuple(locant for locant, _ in surplus),
+                atom_ids=tuple(atom_idx for _, atom_idx in surplus),
+                operation_kind="additive_hydrogen",
+            )
+        )
+
     for locant, atom_idx in candidates:
         parts.indicated_hydrogens.append(locant)
         parts.hydro_operations.append(

src/openclatura/assembler.py

@@ -362,10 +362,17 @@ def _add_indicated_hydrogen_prefix(parts: AssemblyParts, core_name: str) -> str:
         return core_name
     if indicated_hydrogens:
         indicated_hydrogens = sorted(set(indicated_hydrogens), key=parse_locant)
-        core_name = ",".join(indicated_hydrogens) + "H-" + core_name
+        # Every cited position carries its own H -- ``1H,7H-purine``, not
+        # ``1,7H-purine``, which is not a readable name.
+        core_name = ",".join(f"{locant}H" for locant in indicated_hydrogens) + "-" + core_name
     if additive_hydrogens:
         additive_hydrogens = sorted(set(additive_hydrogens), key=parse_locant)
-        core_name = f"{','.join(additive_hydrogens)}-{format_multiplier('hydro', len(additive_hydrogens))}{core_name}"
+        # A locant may not butt against the prefix before it, so a hydro prefix
+        # followed by indicated hydrogen needs a separator:
+        # ``3,7-dihydro-1H-purine-2,6-dione``.
+        separator = "-" if core_name[:1].isdigit() else ""
+        hydro = format_multiplier("hydro", len(additive_hydrogens))
+        core_name = f"{','.join(additive_hydrogens)}-{hydro}{separator}{core_name}"
     return core_name
 
 

src/openclatura/assembly_parts.py

@@ -116,6 +116,11 @@ class RetainedParentMetadata:
     default_indicated_h: tuple[str, ...] = ()
     fusion_locants: tuple[str, ...] = ()
     derivative_stem: str | None = None
+    # How many indicated hydrogens the mancude parent hydride itself supports.
+    # Saturated positions beyond this many are *added* hydrogen and are cited as
+    # a hydro prefix: xanthine is 3,7-dihydro-1H-purine-2,6-dione, never
+    # 1H,3H,7H-purine-2,6-dione.
+    indicated_hydrogen_count: int = 0
 
 
 @dataclass

src/openclatura/retained_fused_production.py

@@ -92,10 +92,28 @@ def production_retained_fused_parent(
             default_indicated_h=template.default_indicated_h,
             fusion_locants=template.fusion_atoms,
             derivative_stem=template.derivative_stem,
+            indicated_hydrogen_count=_indicated_hydrogen_count(template),
         ),
     )
 
 
+def _indicated_hydrogen_count(template) -> int:
+    """How many indicated hydrogens this mancude parent hydride supports.
+
+    A parent that declares its own positions (1H-indole, 9H-xanthene) supports
+    exactly that many.  Otherwise the mancude double-bond count leaves the
+    skeletal atoms it cannot pair: purine's nine atoms and four double bonds
+    leave one, which is why purine is cited as 7H- or 9H-.  A parent with
+    neither is fully mancude and supports none.
+    """
+
+    if template.default_indicated_h:
+        return len(template.default_indicated_h)
+    if template.mancude_double_bonds:
+        return len(template.atoms) - 2 * template.mancude_double_bonds
+    return 0
+
+
 def _neutral_component(mol: Molecule, atoms: set[int]) -> bool:
     return all(mol.atoms[atom].charge == 0 for atom in atoms)
 

src/openclatura/tests/test_analysis.py

@@ -1318,7 +1318,21 @@ def test_repeated_grouped_locants_use_following_structural_scope():
 def test_caffeine_uses_the_retained_purine_dione_parent():
     analysis = analyze_smiles("CN1C=NC2=C1C(=O)N(C(=O)N2C)C")
 
-    assert analysis.name == "1,3,7-trimethylpurine-2,6-dione"
+    # Purine supports one indicated hydrogen; the 2,6-dione saturates two more
+    # positions, which are added hydrogen and take a hydro prefix.  Those
+    # positions count even though all three nitrogens here carry a methyl
+    # rather than a hydrogen.
+    assert analysis.name == "1,3,7-trimethyl-3,7-dihydro-1H-purine-2,6-dione"
+
+
+def test_purine_diones_cite_added_hydrogen_as_a_hydro_prefix():
+    assert name_smiles("O=c1[nH]c(=O)c2[nH]cnc2[nH]1") == "3,7-dihydro-1H-purine-2,6-dione"
+    assert name_smiles("Cn1c(=O)c2[nH]cnc2n(C)c1=O") == "1,3-dimethyl-3,7-dihydro-1H-purine-2,6-dione"
+    # An odd surplus cannot be spelt with a hydro prefix, so it stays indicated.
+    assert name_smiles("O=c1[nH]cnc2[nH]cnc12") == "1H,9H-purin-6-one"
+    # A parent needing no added hydrogen is unaffected.
+    assert name_smiles("c1ncc2[nH]cnc2n1") == "7H-purine"
+    assert name_smiles("Nc1ncnc2[nH]cnc12") == "9H-purin-6-amine"
 
 
 def test_purinone_fusion_carbon_hydrogen_uses_a_dihydro_prefix():