molbuilder 1.0.0__py3-none-any.whl

molbuilder/smiles/tokenizer.py

@@ -0,0 +1,291 @@
+"""SMILES string tokenizer.
+
+Converts a SMILES string into a sequence of Token objects for the parser.
+
+Handles:
+- Organic subset atoms: B, C, N, O, P, S, F, Cl, Br, I (uppercase)
+- Bracket atoms: [NH3+], [Fe], [13C], etc.
+- Aromatic atoms: b, c, n, o, p, s (lowercase)
+- Bond types: - (single), = (double), # (triple), : (aromatic)
+- Branch notation: ( and )
+- Ring closure digits: 0-9, and %nn for two-digit ring numbers
+- Dot disconnection: .
+- Hydrogen counts in brackets: [NH2], [CH3]
+- Charges in brackets: +, -, +2, -1
+- Isotopes in brackets: [13C], [2H]
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum, auto
+
+
+# ===================================================================
+# Token types and data class
+# ===================================================================
+
+class TokenType(Enum):
+    ATOM = auto()           # organic subset atom or bracket atom
+    BOND = auto()           # -, =, #, :
+    BRANCH_OPEN = auto()    # (
+    BRANCH_CLOSE = auto()   # )
+    RING_DIGIT = auto()     # ring closure number
+    DOT = auto()            # . (disconnection)
+
+
+@dataclass
+class Token:
+    """A single lexical token from a SMILES string.
+
+    Attributes
+    ----------
+    type : TokenType
+        The category of this token.
+    value : str
+        The atom symbol for ATOM tokens, the bond character for BOND
+        tokens, or the digit string for RING_DIGIT tokens.
+    isotope : int | None
+        Mass number from a bracket atom, e.g. 13 in ``[13C]``.
+    hcount : int | None
+        Explicit hydrogen count from a bracket atom, e.g. 2 in ``[NH2]``.
+        ``None`` means no explicit H specification (implicit semantics
+        apply).  ``0`` means explicitly zero hydrogens.
+    charge : int
+        Formal charge from a bracket atom, e.g. +1 in ``[NH4+]``.
+    aromatic : bool
+        True if the atom was given in lowercase (aromatic notation).
+    chirality : str | None
+        Chirality marker from a bracket atom: ``"@"`` (anticlockwise),
+        ``"@@"`` (clockwise), or ``None`` (no chirality specified).
+    """
+    type: TokenType
+    value: str
+    isotope: int | None = None
+    hcount: int | None = None
+    charge: int = 0
+    aromatic: bool = False
+    chirality: str | None = None
+
+
+# ===================================================================
+# Constants
+# ===================================================================
+
+# Organic subset: atoms that don't need brackets
+ORGANIC_SUBSET = {"B", "C", "N", "O", "P", "S", "F", "Cl", "Br", "I"}
+AROMATIC_ATOMS = {"b", "c", "n", "o", "p", "s"}
+
+# Two-letter organic subset atoms (checked before single-letter)
+TWO_LETTER_ORGANIC = {"Cl", "Br"}
+
+# Default valence for implicit hydrogen calculation
+DEFAULT_VALENCE: dict[str, list[int]] = {
+    "B": [3], "C": [4], "N": [3, 5], "O": [2], "P": [3, 5],
+    "S": [2, 4, 6], "F": [1], "Cl": [1], "Br": [1], "I": [1],
+    "b": [3], "c": [4], "n": [3], "o": [2], "p": [3], "s": [2],
+}
+
+BOND_CHARS = {"-", "=", "#", ":", "/", "\\"}
+
+
+# ===================================================================
+# Bracket-atom parser helper
+# ===================================================================
+
+def _parse_bracket(smiles: str, start: int) -> tuple[Token, int]:
+    """Parse a bracket atom ``[...]`` starting at *start* (the ``[``).
+
+    Returns the Token and the index of the character after the closing
+    ``]``.
+    """
+    pos = start + 1  # skip '['
+    end = smiles.index("]", pos)
+    inner = smiles[pos:end]
+
+    isotope: int | None = None
+    symbol: str = ""
+    hcount: int | None = None
+    charge: int = 0
+    aromatic: bool = False
+    chirality: str | None = None
+
+    i = 0
+    n = len(inner)
+
+    # --- isotope (leading digits) ---
+    iso_start = i
+    while i < n and inner[i].isdigit():
+        i += 1
+    if i > iso_start:
+        isotope = int(inner[iso_start:i])
+
+    # --- element symbol ---
+    # Symbol starts with an uppercase letter followed by optional lowercase,
+    # OR a single lowercase letter for aromatic atoms.
+    if i < n and inner[i].isupper():
+        symbol = inner[i]
+        i += 1
+        while i < n and inner[i].islower():
+            symbol += inner[i]
+            i += 1
+    elif i < n and inner[i].islower():
+        # aromatic bracket atom
+        symbol = inner[i]
+        aromatic = True
+        i += 1
+    else:
+        raise ValueError(
+            f"Expected element symbol in bracket atom: [{inner}]")
+
+    # --- chirality (@, @@) ---
+    if i < n and inner[i] == "@":
+        i += 1
+        if i < n and inner[i] == "@":
+            chirality = "@@"
+            i += 1
+        else:
+            chirality = "@"
+
+    # --- hydrogen count ---
+    if i < n and inner[i] == "H":
+        i += 1
+        h_start = i
+        while i < n and inner[i].isdigit():
+            i += 1
+        if i > h_start:
+            hcount = int(inner[h_start:i])
+        else:
+            hcount = 1  # bare H means 1 hydrogen
+
+    # --- charge ---
+    if i < n and inner[i] in ("+", "-"):
+        sign = 1 if inner[i] == "+" else -1
+        i += 1
+        ch_start = i
+        while i < n and inner[i].isdigit():
+            i += 1
+        if i > ch_start:
+            charge = sign * int(inner[ch_start:i])
+        else:
+            # Count consecutive +/- signs (e.g. ++ means +2)
+            extra = 0
+            ch = "+" if sign == 1 else "-"
+            while i < n and inner[i] == ch:
+                extra += 1
+                i += 1
+            charge = sign * (1 + extra)
+
+    return Token(
+        type=TokenType.ATOM,
+        value=symbol,
+        isotope=isotope,
+        hcount=hcount,
+        charge=charge,
+        aromatic=aromatic,
+        chirality=chirality,
+    ), end + 1
+
+
+# ===================================================================
+# Main tokenizer
+# ===================================================================
+
+def tokenize(smiles: str) -> list[Token]:
+    """Convert a SMILES string into a list of Token objects.
+
+    Parameters
+    ----------
+    smiles : str
+        A valid SMILES string, e.g. ``"CCO"``, ``"c1ccccc1"``,
+        ``"[NH4+]"``.
+
+    Returns
+    -------
+    list[Token]
+        Ordered sequence of tokens ready for the parser.
+
+    Raises
+    ------
+    ValueError
+        If the string contains unexpected characters or malformed
+        bracket atoms.
+    """
+    tokens: list[Token] = []
+    i = 0
+    n = len(smiles)
+
+    while i < n:
+        ch = smiles[i]
+
+        # --- bracket atom ---
+        if ch == "[":
+            token, i = _parse_bracket(smiles, i)
+            tokens.append(token)
+            continue
+
+        # --- two-letter organic atoms (Cl, Br) ---
+        if i + 1 < n and smiles[i:i + 2] in TWO_LETTER_ORGANIC:
+            tokens.append(Token(type=TokenType.ATOM, value=smiles[i:i + 2]))
+            i += 2
+            continue
+
+        # --- single-letter organic subset atoms ---
+        if ch in {"B", "C", "N", "O", "P", "S", "F", "I"}:
+            tokens.append(Token(type=TokenType.ATOM, value=ch))
+            i += 1
+            continue
+
+        # --- aromatic atoms ---
+        if ch in {"b", "c", "n", "o", "p", "s"}:
+            tokens.append(Token(
+                type=TokenType.ATOM, value=ch, aromatic=True))
+            i += 1
+            continue
+
+        # --- bond symbols ---
+        if ch in BOND_CHARS:
+            tokens.append(Token(type=TokenType.BOND, value=ch))
+            i += 1
+            continue
+
+        # --- branch open / close ---
+        if ch == "(":
+            tokens.append(Token(type=TokenType.BRANCH_OPEN, value="("))
+            i += 1
+            continue
+
+        if ch == ")":
+            tokens.append(Token(type=TokenType.BRANCH_CLOSE, value=")"))
+            i += 1
+            continue
+
+        # --- ring closure digit ---
+        if ch.isdigit():
+            tokens.append(Token(type=TokenType.RING_DIGIT, value=ch))
+            i += 1
+            continue
+
+        # --- two-digit ring closure: %nn ---
+        if ch == "%":
+            if i + 2 >= n or not smiles[i + 1].isdigit() or not smiles[i + 2].isdigit():
+                raise ValueError(
+                    f"Expected two digits after '%' at position {i}")
+            tokens.append(Token(
+                type=TokenType.RING_DIGIT,
+                value=smiles[i + 1:i + 3]))
+            i += 3
+            continue
+
+        # --- dot disconnection ---
+        if ch == ".":
+            tokens.append(Token(type=TokenType.DOT, value="."))
+            i += 1
+            continue
+
+        # --- unexpected character ---
+        raise ValueError(
+            f"Unexpected character {ch!r} at position {i} in SMILES "
+            f"string {smiles!r}")
+
+    return tokens

molbuilder/smiles/writer.py

@@ -0,0 +1,375 @@
+"""SMILES writer: Molecule -> canonical SMILES string.
+
+Uses Morgan's algorithm for canonical atom numbering, then DFS traversal
+to generate the SMILES string.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+
+from molbuilder.molecule.graph import Molecule
+from molbuilder.core.elements import SYMBOL_TO_Z
+from molbuilder.smiles.tokenizer import ORGANIC_SUBSET, DEFAULT_VALENCE
+
+
+# ===================================================================
+# Morgan canonical ordering
+# ===================================================================
+
+def _morgan_canonical_order(mol: Molecule) -> dict[int, int]:
+    """Compute canonical atom ranks using Morgan's extended connectivity.
+
+    Algorithm
+    ---------
+    1. Initialize each atom's invariant to its degree (number of
+       neighbours).
+    2. Iteratively replace each atom's invariant with the sum of its
+       neighbours' invariants until the number of distinct values
+       stabilises.
+    3. Break ties using atomic number (higher Z = higher rank).
+    4. Return a mapping from atom index to rank (0 = lowest priority,
+       first in canonical order).
+
+    Parameters
+    ----------
+    mol : Molecule
+        The molecule whose atoms should be ranked.
+
+    Returns
+    -------
+    dict[int, int]
+        Mapping from atom index to canonical rank.
+    """
+    n = len(mol.atoms)
+    if n == 0:
+        return {}
+
+    # Initial connectivity value = degree
+    ec = [len(mol.neighbors(i)) for i in range(n)]
+
+    prev_classes = 0
+    for _iteration in range(100):
+        new_ec = [0] * n
+        for i in range(n):
+            new_ec[i] = sum(ec[j] for j in mol.neighbors(i))
+
+        # Count distinct classes
+        classes = len(set(new_ec))
+        if classes == prev_classes:
+            break
+        prev_classes = classes
+        ec = new_ec
+
+    # Build (ec_value, atomic_number, original_index) for stable sort
+    sort_keys = []
+    for i in range(n):
+        z = SYMBOL_TO_Z.get(mol.atoms[i].symbol, 0)
+        sort_keys.append((ec[i], z, i))
+
+    sorted_atoms = sorted(sort_keys)
+    order: dict[int, int] = {}
+    for rank, (_, _, idx) in enumerate(sorted_atoms):
+        order[idx] = rank
+
+    return order
+
+
+# ===================================================================
+# Connected components
+# ===================================================================
+
+def _connected_components(mol: Molecule) -> list[list[int]]:
+    """Return lists of atom indices for each connected fragment.
+
+    Considers only heavy (non-hydrogen) atoms.
+    """
+    n = len(mol.atoms)
+    heavy = {i for i in range(n) if mol.atoms[i].symbol != "H"}
+    visited: set[int] = set()
+    components: list[list[int]] = []
+
+    for start in heavy:
+        if start in visited:
+            continue
+        comp: list[int] = []
+        stack = [start]
+        while stack:
+            cur = stack.pop()
+            if cur in visited:
+                continue
+            visited.add(cur)
+            if cur not in heavy:
+                continue
+            comp.append(cur)
+            for nb in mol.neighbors(cur):
+                if nb not in visited and nb in heavy:
+                    stack.append(nb)
+        if comp:
+            components.append(comp)
+
+    return components
+
+
+# ===================================================================
+# Bond order symbol
+# ===================================================================
+
+def _bond_symbol(mol: Molecule, i: int, j: int) -> str:
+    """Return the SMILES bond symbol between atoms *i* and *j*.
+
+    Single bonds return ``""`` (implicit), double ``"="``, triple ``"#"``.
+    """
+    bond = mol.get_bond(i, j)
+    if bond is None:
+        return ""
+    if bond.order == 2:
+        return "="
+    if bond.order == 3:
+        return "#"
+    return ""
+
+
+# ===================================================================
+# DFS SMILES generation
+# ===================================================================
+
+def _dfs_smiles(mol: Molecule, order: dict[int, int],
+                component: list[int]) -> str:
+    """Generate a SMILES string for one connected component via DFS.
+
+    Parameters
+    ----------
+    mol : Molecule
+        The full molecule.
+    order : dict[int, int]
+        Canonical ranking from ``_morgan_canonical_order``.
+    component : list[int]
+        Atom indices belonging to this fragment (heavy atoms only).
+
+    Returns
+    -------
+    str
+        SMILES string for the fragment.
+    """
+    if not component:
+        return ""
+
+    comp_set = set(component)
+
+    # Start DFS from the atom with the lowest canonical rank in this component
+    start = min(component, key=lambda i: order.get(i, 0))
+
+    visited: set[int] = set()
+    # Track ring closure pairs: when DFS finds a back-edge, both
+    # endpoints get a digit.
+    ring_bonds: dict[tuple[int, int], int] = {}
+    next_ring_digit = 1
+
+    parts: list[str] = []
+
+    def _heavy_neighbors(idx: int) -> list[int]:
+        """Return non-hydrogen neighbours in this component, sorted by
+        canonical rank (highest rank = most preferred child = last in
+        the sort so it gets visited first on the main chain)."""
+        nbs = []
+        for nb in mol.neighbors(idx):
+            if mol.atoms[nb].symbol == "H":
+                continue
+            if nb not in comp_set:
+                continue
+            nbs.append(nb)
+        # Sort: the *last* element becomes the "main chain" child (no
+        # parentheses).  Lower rank = visited first = branch.
+        nbs.sort(key=lambda x: order.get(x, 0))
+        return nbs
+
+    def _atom_str(idx: int) -> str:
+        """Return the SMILES atom token for atom *idx*.
+
+        Outputs bracket notation ``[<isotope><symbol><chirality><hcount><charge>]``
+        when the atom has non-default properties (chirality, isotope, charge,
+        or is not in the organic subset).  Organic subset atoms without
+        special properties are written without brackets.
+        """
+        atom = mol.atoms[idx]
+        sym = atom.symbol
+        has_chirality = atom.chirality is not None
+        has_isotope = atom.isotope is not None
+        has_charge = atom.formal_charge != 0
+        needs_bracket = has_chirality or has_isotope or has_charge or sym not in ORGANIC_SUBSET
+
+        if not needs_bracket:
+            return sym
+
+        # Build bracket atom string: [<isotope><symbol><chirality><Hn><charge>]
+        parts: list[str] = []
+        if has_isotope:
+            parts.append(str(atom.isotope))
+        parts.append(sym)
+        if has_chirality:
+            parts.append(atom.chirality)
+
+        # Compute implicit H count: count explicit H neighbours
+        h_count = sum(1 for nb in mol.neighbors(idx)
+                      if mol.atoms[nb].symbol == "H")
+        if h_count == 1:
+            parts.append("H")
+        elif h_count > 1:
+            parts.append(f"H{h_count}")
+
+        if has_charge:
+            ch = atom.formal_charge
+            if ch == 1:
+                parts.append("+")
+            elif ch == -1:
+                parts.append("-")
+            elif ch > 0:
+                parts.append(f"+{ch}")
+            else:
+                parts.append(str(ch))
+
+        return f"[{''.join(parts)}]"
+
+    def _emit_ring_closure(idx: int, nb: int) -> None:
+        """Register and emit a ring closure digit between idx and nb."""
+        nonlocal next_ring_digit
+        edge = (min(idx, nb), max(idx, nb))
+        if edge not in ring_bonds:
+            ring_bonds[edge] = next_ring_digit
+            next_ring_digit += 1
+        digit = ring_bonds[edge]
+        bsym = _bond_symbol(mol, idx, nb)
+        if digit < 10:
+            parts.append(f"{bsym}{digit}")
+        else:
+            parts.append(f"{bsym}%{digit:02d}")
+
+    def _dfs(idx: int, parent: int | None = None) -> None:
+        visited.add(idx)
+        parts.append(_atom_str(idx))
+
+        # Classify neighbours into ring closures and tree children
+        nbs = _heavy_neighbors(idx)
+        parent_consumed = False
+        ring_nbs: list[int] = []
+        unvisited_nbs: list[int] = []
+
+        for nb in nbs:
+            if nb == parent and not parent_consumed:
+                # Skip the tree edge we arrived on (consume once)
+                parent_consumed = True
+                continue
+            if nb in visited:
+                ring_nbs.append(nb)
+            else:
+                unvisited_nbs.append(nb)
+
+        # Emit ring closure digits at this atom
+        for nb in ring_nbs:
+            _emit_ring_closure(idx, nb)
+
+        if not unvisited_nbs:
+            return
+
+        # Process children.  All except the last become branches
+        # (wrapped in parentheses); the last is the main chain.
+        # After each branch, re-check whether later children have
+        # been visited (they may have been reached through a ring
+        # inside the branch -- in that case emit the ring closure
+        # digit at this atom's position).
+        remaining = list(unvisited_nbs)
+        while remaining:
+            # Promote children visited during a sibling branch to ring
+            # closures: their partner already emitted the digit, so we
+            # must emit the matching digit here.
+            still_unvisited: list[int] = []
+            for c in remaining:
+                if c in visited:
+                    edge = (min(idx, c), max(idx, c))
+                    if edge in ring_bonds:
+                        _emit_ring_closure(idx, c)
+                    # else: already handled or no ring bond -- skip
+                else:
+                    still_unvisited.append(c)
+            remaining = still_unvisited
+
+            if not remaining:
+                return
+
+            if len(remaining) == 1:
+                # Last remaining child: main chain, no parentheses
+                child = remaining[0]
+                bsym = _bond_symbol(mol, idx, child)
+                parts.append(bsym)
+                _dfs(child, parent=idx)
+                return
+
+            # Branch child (not the last one)
+            child = remaining.pop(0)
+            if child in visited:
+                # Reached through another path; ring closure
+                _emit_ring_closure(idx, child)
+            else:
+                bsym = _bond_symbol(mol, idx, child)
+                parts.append(f"({bsym}")
+                _dfs(child, parent=idx)
+                parts.append(")")
+
+    _dfs(start)
+
+    # Also emit ring closure digits for atoms that have back-edge
+    # partners not yet annotated.  (The partner side is handled when
+    # the DFS visits that atom -- it adds the digit there.)
+    # In the standard algorithm above, both sides are already handled.
+
+    return "".join(parts)
+
+
+# ===================================================================
+# Public API
+# ===================================================================
+
+def to_smiles(mol: Molecule) -> str:
+    """Convert a Molecule to a SMILES string.
+
+    Hydrogen atoms are omitted (they are implicit in SMILES notation).
+    Multi-fragment molecules are joined with ``.`` separators.
+
+    Parameters
+    ----------
+    mol : Molecule
+        A molecule built with the ``molbuilder`` framework.
+
+    Returns
+    -------
+    str
+        A SMILES string representing the molecule.
+
+    Examples
+    --------
+    >>> from molbuilder.smiles.parser import parse
+    >>> mol = parse("CCO")
+    >>> to_smiles(mol)  # may return "CCO" or "OCC" depending on canonicalization
+    '...'
+    """
+    if not mol.atoms:
+        return ""
+
+    order = _morgan_canonical_order(mol)
+    components = _connected_components(mol)
+
+    if not components:
+        return ""
+
+    # Sort components for deterministic output (largest first,
+    # then by lowest canonical rank of their start atom)
+    components.sort(key=lambda c: (-len(c), min(order.get(i, 0) for i in c)))
+
+    fragments = []
+    for comp in components:
+        smi = _dfs_smiles(mol, order, comp)
+        if smi:
+            fragments.append(smi)
+
+    return ".".join(fragments)

molbuilder/visualization/__init__.py

@@ -0,0 +1 @@
+"""Visualization: Bohr models, orbital clouds, molecule rendering."""