Merge pull request #772 from Steinbeck-Lab/development

Add multi-frame XYZ conversion features and refactor types

Author: Kohulan

app/modules/toolkits/helpers.py

@@ -70,3 +70,84 @@ def parse_SMILES(smiles: str, framework: str = "rdkit", standardize: bool = Fals
             return Chem.MolFromMolBlock(mol_str)
     except Exception:
         raise InvalidInputException(name="smiles", value=smiles)
+
+
+def _is_plausible_atom_row(line: str) -> bool:
+    """Return True if *line* looks like a valid XYZ atom row.
+
+    A plausible row, after stripping, has at least 4 whitespace-separated
+    tokens where the first token starts with an ASCII letter (element symbol)
+    and tokens 2-4 are parseable as floats (the x, y, z coordinates).
+    """
+    parts = line.strip().split()
+    if len(parts) < 4:
+        return False
+    if not parts[0][0].isascii() or not parts[0][0].isalpha():
+        return False
+    try:
+        float(parts[1])
+        float(parts[2])
+        float(parts[3])
+    except ValueError:
+        return False
+    return True
+
+
+def split_xyz_frames(xyz_data: str) -> list[str]:
+    """Split a multi-frame XYZ string into a list of single-frame XYZ strings.
+
+    XYZ format: each record is ``<atom_count>\\n<comment>\\n<atom_count atom rows>``.
+    A multi-record file simply concatenates these blocks.
+
+    The splitter is permissive:
+
+    * Accepts CRLF or LF line endings (output is always LF).
+    * Recovers the next valid frame after a truncated or garbage block by
+      advancing one line at a time rather than aborting the whole parse.
+    * Validates each candidate atom row before accepting a block, so a fake
+      ``atom_count`` cannot greedily consume real lines from the next frame.
+    * Drops zero-atom frames (degenerate).
+    * Normalizes the count line (strips surrounding whitespace).
+    * Each emitted frame is itself a valid XYZ string ending in ``\\n``.
+
+    Args:
+        xyz_data: Raw text, possibly containing multiple concatenated XYZ records.
+
+    Returns:
+        A list of self-contained single-frame XYZ strings. Empty list if the
+        input contains no recognizable frames.
+    """
+    if not xyz_data or not xyz_data.strip():
+        return []
+
+    lines = xyz_data.replace("\r\n", "\n").replace("\r", "\n").split("\n")
+    frames: list[str] = []
+    i = 0
+    n = len(lines)
+    while i < n:
+        token = lines[i].strip()
+        if not token.isdecimal():
+            i += 1
+            continue
+        atom_count = int(token)
+        if atom_count == 0:
+            # Skip the count line + the comment line; emit nothing.
+            i += 2
+            continue
+        # Need atom_count + 2 (count + comment + atoms) lines starting at i.
+        end = i + 2 + atom_count
+        if end > n:
+            # Truncated frame: advance by one line and keep scanning.
+            i += 1
+            continue
+        # Validate every candidate atom row before accepting the block.
+        atom_rows = lines[i + 2 : end]
+        if not all(_is_plausible_atom_row(row) for row in atom_rows):
+            i += 1
+            continue
+        # Normalize the count line; keep all other lines verbatim.
+        block_lines = [lines[i].strip()] + lines[i + 1 : end]
+        # Each emitted frame ends in exactly one newline.
+        frames.append("\n".join(block_lines) + "\n")
+        i = end
+    return frames

app/modules/toolkits/rdkit_wrapper.py

@@ -1038,50 +1038,42 @@ def convert_xyz_to_mol(
     embed_chiral: bool = True,
     use_huckel: bool = False,
     cov_factor: float = 1.3,
-) -> Chem.Mol:
-    """Parse an XYZ block and assign connectivity + bond orders via xyz2mol.
+) -> tuple[Chem.Mol, str]:
+    """Parse an XYZ block and assign bonds via a two-tier RDKit pipeline.
 
-    Reads coordinates with ``Chem.MolFromXYZBlock`` (which yields a Mol with
-    only atoms and a 3D conformer, no bonds), copies it via ``Chem.Mol(raw)``
-    so the original is preserved, then runs ``rdDetermineBonds.DetermineBonds``
-    to perceive connectivity *and* bond orders in a single charge-aware pass.
+    Tier 1: ``rdDetermineBonds.DetermineBonds`` (xyz2mol) -- full bond-order
+        perception, charge-aware. Works for organic/main-group molecules.
+    Tier 2 (only if Tier 1 raises): ``rdDetermineBonds.DetermineConnectivity``
+        -- VdW connect-the-dots, all bonds order 1, but works for any element
+        including transition metals. Information-poor but accurate-by-construction.
 
     Args:
-        xyz_data (str): Plain-text XYZ block (atom count, comment line, then
-            ``element x y z`` rows). Must include the header lines.
-        charge (int): Net molecular charge. Required for non-neutral species.
-            Defaults to 0.
-        allow_charged_fragments (bool): If True, place formal charges on
-            atoms; if False, assign radical electrons instead. Defaults to
-            True (matches xyz2mol's default behavior).
-        embed_chiral (bool): Embed chirality information from 3D coords.
-            Defaults to True.
-        use_huckel (bool): Use extended Hückel theory for bond perception
-            instead of the van der Waals method. More accurate for
-            unusual valences but slower. Defaults to False.
-        cov_factor (float): Multiplier on covalent radii for VdW
-            connect-the-dots. Defaults to 1.3.
+        xyz_data: Plain-text XYZ block including the count + comment header.
+        charge: Net molecular charge (Tier 1 only). Defaults to 0.
+        allow_charged_fragments: xyz2mol option (Tier 1 only). Defaults to True.
+        embed_chiral: xyz2mol option (Tier 1 only). Defaults to True.
+        use_huckel: Use extended Huckel theory in Tier 1. Defaults to False.
+        cov_factor: Covalent-radius multiplier (both tiers). Defaults to 1.3.
 
     Returns:
-        Chem.Mol: RDKit molecule with 3D conformer and perceived bonds.
+        A tuple ``(mol, method)`` where ``method`` is one of
+        ``"bond_orders"`` (Tier 1) or ``"connectivity_only"`` (Tier 2).
 
     Raises:
-        ValueError: If the XYZ block cannot be parsed or bond perception
-            fails (malformed input, unknown elements, geometry that cannot
-            be reconciled with the requested charge).
+        ValueError: If the XYZ block cannot be parsed, or if both tiers fail.
     """
     if not xyz_data or not xyz_data.strip():
         raise ValueError("Empty XYZ data.")
 
     raw_mol = Chem.MolFromXYZBlock(xyz_data)
     if raw_mol is None:
         raise ValueError("Failed to parse XYZ block.")
-
     if raw_mol.GetNumAtoms() == 0:
         raise ValueError("XYZ block contains no atoms.")
 
-    mol = Chem.Mol(raw_mol)
+    # Tier 1: full bond-order perception via xyz2mol.
     try:
+        mol = Chem.Mol(raw_mol)
         rdDetermineBonds.DetermineBonds(
             mol,
             charge=charge,
@@ -1090,7 +1082,16 @@ def convert_xyz_to_mol(
             useHueckel=use_huckel,
             covFactor=cov_factor,
         )
-    except (ValueError, RuntimeError) as exc:
-        raise ValueError(f"Bond perception failed: {exc}") from exc
+        return mol, "bond_orders"
+    except (ValueError, RuntimeError) as tier1_exc:
+        tier1_err = str(tier1_exc)
 
-    return mol
+    # Tier 2: connectivity-only (VdW connect-the-dots). Works for any element.
+    try:
+        mol = Chem.Mol(raw_mol)
+        rdDetermineBonds.DetermineConnectivity(mol, covFactor=cov_factor)
+        return mol, "connectivity_only"
+    except (ValueError, RuntimeError) as tier2_exc:
+        raise ValueError(
+            f"Bond perception failed (tier 1: {tier1_err}; tier 2: {tier2_exc})"
+        ) from tier2_exc