molbuilder 1.0.0__py3-none-any.whl

molbuilder/io/mol_sdf.py

@@ -0,0 +1,169 @@
+"""V2000 MOL/SDF file format reader/writer.
+
+MOL file layout (V2000)::
+
+    <molecule name>
+      molbuilder          3D
+
+     <atom_count> <bond_count>  0  0  0  0  0  0  0  0999 V2000
+    <x10.4><y10.4><z10.4> <sym3> 0  0  0  0  0  0  0  0  0  0  0  0
+    ...
+    <i3><j3><type3>  0  0  0  0
+    ...
+    M  END
+
+SDF files contain one or more MOL blocks separated by ``$$$$``.
+
+Note: MOL files use **1-based** atom indices.
+Bond type: 1 = single, 2 = double, 3 = triple.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from molbuilder.molecule.graph import Molecule, Hybridization
+
+
+# ── MOL string serialisation ─────────────────────────────────────────
+
+def to_mol_string(mol: Molecule) -> str:
+    """Serialise a Molecule to a V2000 MOL block string."""
+    lines: list[str] = []
+
+    # Header block (3 lines)
+    lines.append(mol.name if mol.name else "")
+    lines.append("  molbuilder          3D")
+    lines.append("")
+
+    # Counts line
+    n_atoms = len(mol.atoms)
+    n_bonds = len(mol.bonds)
+    lines.append(
+        f"{n_atoms:3d}{n_bonds:3d}"
+        f"  0  0  0  0  0  0  0  0999 V2000"
+    )
+
+    # Atom block
+    for atom in mol.atoms:
+        x, y, z = atom.position
+        symbol = atom.symbol
+        lines.append(
+            f"{x:10.4f}{y:10.4f}{z:10.4f} {symbol:<3s} 0  0  0  0  0  0  0  0  0  0  0  0"
+        )
+
+    # Bond block
+    for bond in mol.bonds:
+        i = bond.atom_i + 1  # 1-based
+        j = bond.atom_j + 1
+        order = bond.order
+        lines.append(f"{i:3d}{j:3d}{order:3d}  0  0  0  0")
+
+    lines.append("M  END")
+    return "\n".join(lines) + "\n"
+
+
+def from_mol_string(content: str) -> Molecule:
+    """Parse a Molecule from a V2000 MOL block string."""
+    lines = content.splitlines()
+
+    # Header
+    name = lines[0].strip() if lines[0].strip() else ""
+    # lines[1] = program/timestamp, lines[2] = comment (both ignored)
+
+    # Counts line
+    counts_line = lines[3]
+    n_atoms = int(counts_line[0:3])
+    n_bonds = int(counts_line[3:6])
+
+    if len(lines) < 4 + n_atoms + n_bonds:
+        raise ValueError(f"MOL file truncated: expected {4 + n_atoms + n_bonds} lines")
+
+    mol = Molecule(name=name)
+
+    # Atom block: starts at line 4
+    for i in range(n_atoms):
+        line = lines[4 + i]
+        x = float(line[0:10])
+        y = float(line[10:20])
+        z = float(line[20:30])
+        symbol = line[31:34].strip()
+        mol.add_atom(symbol, [x, y, z])
+
+    # Bond block: starts after atom block
+    bond_start = 4 + n_atoms
+    for i in range(n_bonds):
+        line = lines[bond_start + i]
+        ai = int(line[0:3]) - 1   # convert to 0-based
+        aj = int(line[3:6]) - 1
+        order = int(line[6:9])
+        rotatable = (order == 1)
+        mol.add_bond(ai, aj, order=order, rotatable=rotatable)
+
+    return mol
+
+
+# ── MOL file I/O ─────────────────────────────────────────────────────
+
+def write_mol(mol: Molecule, filepath: str) -> None:
+    """Write a Molecule to a V2000 MOL file."""
+    with open(filepath, "w") as f:
+        f.write(to_mol_string(mol))
+
+
+def read_mol(filepath: str) -> Molecule:
+    """Read a Molecule from a V2000 MOL file."""
+    with open(filepath, "r") as f:
+        content = f.read()
+    return from_mol_string(content)
+
+
+# ── SDF multi-molecule I/O ───────────────────────────────────────────
+
+def write_sdf(molecules: list[Molecule], filepath: str) -> None:
+    """Write multiple Molecules to an SDF file.
+
+    Each MOL block is followed by ``$$$$`` as the record separator.
+    """
+    with open(filepath, "w") as f:
+        for mol in molecules:
+            f.write(to_mol_string(mol))
+            f.write("$$$$\n")
+
+
+def read_sdf(filepath: str) -> list[Molecule]:
+    """Read all Molecules from an SDF file.
+
+    SDF files contain one or more MOL blocks separated by ``$$$$``.
+    Data items between ``M  END`` and ``$$$$`` are silently ignored.
+    """
+    with open(filepath, "r") as f:
+        content = f.read()
+
+    molecules: list[Molecule] = []
+    blocks = content.split("$$$$")
+
+    for block in blocks:
+        block = block.strip()
+        if not block:
+            continue
+
+        # Ensure the block contains a valid MOL section
+        if "V2000" not in block:
+            continue
+
+        # Trim anything after "M  END" (SDF data items)
+        end_idx = block.find("M  END")
+        if end_idx != -1:
+            mol_block = block[:end_idx + len("M  END")]
+        else:
+            mol_block = block
+
+        try:
+            mol = from_mol_string(mol_block)
+            molecules.append(mol)
+        except (ValueError, IndexError):
+            # Skip malformed blocks rather than crashing
+            continue
+
+    return molecules

molbuilder/io/pdb.py

@@ -0,0 +1,184 @@
+"""PDB file format reader/writer.
+
+Supports ATOM/HETATM records for coordinates and CONECT records for
+bond connectivity.  Intended for small-molecule use (not full protein
+PDB support).
+
+Record formats used::
+
+    ATOM      1  C1  MOL A   1       0.000   0.000   0.000  1.00  0.00           C
+    CONECT    1    2    3    4    5
+    END
+"""
+
+from __future__ import annotations
+
+from collections import Counter, defaultdict
+
+import numpy as np
+
+from molbuilder.molecule.graph import Molecule
+
+
+# ── Helpers ───────────────────────────────────────────────────────────
+
+def _atom_names(mol: Molecule) -> list[str]:
+    """Generate PDB atom names (e.g. C1, C2, H1, H2, ...) for each atom
+    based on its element and order of occurrence within that element."""
+    counts: Counter[str] = Counter()
+    names: list[str] = []
+    for atom in mol.atoms:
+        counts[atom.symbol] += 1
+        names.append(f"{atom.symbol}{counts[atom.symbol]}")
+    return names
+
+
+def _residue_name(mol: Molecule) -> str:
+    """Return a 3-character residue name derived from the molecule name."""
+    name = mol.name.strip() if mol.name else "MOL"
+    if len(name) == 0:
+        return "MOL"
+    # Uppercase, first 3 characters
+    return name[:3].upper().ljust(3)
+
+
+# ── String serialisation ─────────────────────────────────────────────
+
+def to_pdb_string(mol: Molecule) -> str:
+    """Serialise a Molecule to PDB-format string with ATOM and CONECT
+    records."""
+    lines: list[str] = []
+    atom_names = _atom_names(mol)
+    res_name = _residue_name(mol)
+    chain = "A"
+    res_seq = 1
+
+    # ATOM records
+    for atom in mol.atoms:
+        serial = atom.index + 1  # 1-based
+        aname = atom_names[atom.index]
+        x, y, z = atom.position
+        element = atom.symbol.rjust(2)
+
+        # PDB ATOM record (fixed-width columns)
+        #  1- 6  Record type
+        #  7-11  Serial
+        # 13-16  Atom name
+        # 17     Alternate location
+        # 18-20  Residue name
+        # 22     Chain ID
+        # 23-26  Residue sequence number
+        # 31-38  x (8.3f)
+        # 39-46  y (8.3f)
+        # 47-54  z (8.3f)
+        # 55-60  Occupancy (6.2f)
+        # 61-66  Temp factor (6.2f)
+        # 77-78  Element symbol
+        line = (
+            f"HETATM{serial:5d} {aname:<4s} {res_name:3s} {chain:1s}"
+            f"{res_seq:4d}    "
+            f"{x:8.3f}{y:8.3f}{z:8.3f}"
+            f"{1.0:6.2f}{0.0:6.2f}"
+            f"          {element:>2s}"
+        )
+        lines.append(line)
+
+    # CONECT records
+    # Build adjacency: for each atom, list of bonded atom serials (1-based)
+    adj: dict[int, list[int]] = defaultdict(list)
+    for bond in mol.bonds:
+        adj[bond.atom_i + 1].append(bond.atom_j + 1)
+        adj[bond.atom_j + 1].append(bond.atom_i + 1)
+
+    for serial in sorted(adj):
+        neighbours = sorted(adj[serial])
+        # PDB CONECT records can hold up to 4 bonded atoms per line
+        for chunk_start in range(0, len(neighbours), 4):
+            chunk = neighbours[chunk_start:chunk_start + 4]
+            parts = "".join(f"{n:5d}" for n in chunk)
+            lines.append(f"CONECT{serial:5d}{parts}")
+
+    lines.append("END")
+    return "\n".join(lines) + "\n"
+
+
+def from_pdb_string(content: str) -> Molecule:
+    """Parse a Molecule from PDB-format string.
+
+    Reads HETATM / ATOM records for coordinates and CONECT records for
+    bond connectivity.
+    """
+    mol = Molecule()
+
+    serial_to_index: dict[int, int] = {}
+    conect_records: list[tuple[int, list[int]]] = []
+
+    for line in content.splitlines():
+        record = line[:6].strip()
+
+        if record in ("ATOM", "HETATM"):
+            serial = int(line[6:11])
+            # Element symbol: columns 77-78 (preferred), fallback to atom name
+            element = line[76:78].strip() if len(line) >= 78 else ""
+            if not element:
+                # Fallback: strip digits from atom name (cols 12-16)
+                raw_name = line[12:16].strip()
+                element = "".join(c for c in raw_name if c.isalpha())
+
+            x = float(line[30:38])
+            y = float(line[38:46])
+            z = float(line[46:54])
+
+            idx = mol.add_atom(element, [x, y, z])
+            serial_to_index[serial] = idx
+
+            # Extract molecule name from residue name on first atom
+            if idx == 0:
+                res = line[17:20].strip()
+                mol.name = res
+
+        elif record == "CONECT":
+            serial = int(line[6:11])
+            neighbours: list[int] = []
+            col = 11
+            while col + 5 <= len(line):
+                token = line[col:col + 5].strip()
+                if token:
+                    try:
+                        neighbours.append(int(token))
+                    except ValueError:
+                        pass
+                col += 5
+            conect_records.append((serial, neighbours))
+
+    # Build bonds from CONECT records (avoid duplicates)
+    added_bonds: set[tuple[int, int]] = set()
+    for serial, neighbours in conect_records:
+        if serial not in serial_to_index:
+            continue
+        i = serial_to_index[serial]
+        for nb_serial in neighbours:
+            if nb_serial not in serial_to_index:
+                continue
+            j = serial_to_index[nb_serial]
+            bond_key = (min(i, j), max(i, j))
+            if bond_key not in added_bonds:
+                added_bonds.add(bond_key)
+                mol.add_bond(i, j, order=1, rotatable=True)
+
+    return mol
+
+
+# ── File I/O ──────────────────────────────────────────────────────────
+
+def write_pdb(mol: Molecule, filepath: str) -> None:
+    """Write a Molecule to a PDB file."""
+    with open(filepath, "w") as f:
+        f.write(to_pdb_string(mol))
+
+
+def read_pdb(filepath: str) -> Molecule:
+    """Read a Molecule from a PDB file."""
+    with open(filepath, "r") as f:
+        content = f.read()
+    return from_pdb_string(content)

molbuilder/io/smiles_io.py

@@ -0,0 +1,47 @@
+"""SMILES file I/O wrapper.
+
+Reads and writes SMILES files where each line contains a SMILES string
+optionally followed by a molecule name::
+
+    CCO ethanol
+    c1ccccc1 benzene
+"""
+
+import warnings
+
+from molbuilder.smiles.parser import parse
+from molbuilder.smiles.writer import to_smiles
+from molbuilder.molecule.graph import Molecule
+
+
+def write_smiles(mol: Molecule, filepath: str) -> None:
+    """Write a SMILES string to a file."""
+    smi = to_smiles(mol)
+    with open(filepath, "w") as f:
+        f.write(f"{smi} {mol.name}\n")
+
+
+def read_smiles(filepath: str) -> list[Molecule]:
+    """Read molecules from a SMILES file (one per line).
+
+    Blank lines and lines starting with ``#`` are skipped.  Each line
+    may contain a SMILES string followed by an optional name separated
+    by whitespace.
+    """
+    molecules = []
+    with open(filepath, "r") as f:
+        for line in f:
+            line = line.strip()
+            if not line or line.startswith("#"):
+                continue
+            parts = line.split(None, 1)
+            smi = parts[0]
+            name = parts[1] if len(parts) > 1 else smi
+            try:
+                mol = parse(smi)
+            except (ValueError, IndexError) as e:
+                warnings.warn(f"Skipping invalid SMILES '{smi}': {e}")
+                continue
+            mol.name = name
+            molecules.append(mol)
+    return molecules

molbuilder/io/xyz.py

@@ -0,0 +1,103 @@
+"""XYZ file format reader/writer.
+
+The XYZ format is one of the simplest molecular geometry formats::
+
+    <atom_count>
+    <comment line>
+    <symbol> <x> <y> <z>
+    <symbol> <x> <y> <z>
+    ...
+
+XYZ files do not store bond connectivity, so bonds are inferred from
+interatomic distances and covalent radii when reading.
+"""
+
+from __future__ import annotations
+
+import math
+
+import numpy as np
+
+from molbuilder.molecule.graph import Molecule
+from molbuilder.core.element_properties import covalent_radius_pm
+
+
+# ── Bond inference ────────────────────────────────────────────────────
+
+_BOND_TOLERANCE = 1.3  # multiplier on sum-of-covalent-radii
+
+
+def _infer_bonds(mol: Molecule) -> None:
+    """Add bonds between atoms whose distance is within tolerance of
+    the sum of their covalent radii (converted from pm to Angstroms).
+    """
+    n = len(mol.atoms)
+    for i in range(n):
+        for j in range(i + 1, n):
+            ri = covalent_radius_pm(mol.atoms[i].symbol) / 100.0
+            rj = covalent_radius_pm(mol.atoms[j].symbol) / 100.0
+            max_dist = _BOND_TOLERANCE * (ri + rj)
+            dist = float(np.linalg.norm(
+                mol.atoms[i].position - mol.atoms[j].position))
+            if dist < max_dist:
+                mol.add_bond(i, j, order=1, rotatable=True)
+
+
+# ── String serialisation ─────────────────────────────────────────────
+
+def to_xyz_string(mol: Molecule) -> str:
+    """Return the molecule as an XYZ-format string."""
+    lines: list[str] = []
+    lines.append(str(len(mol.atoms)))
+    lines.append(mol.name if mol.name else "")
+    for atom in mol.atoms:
+        x, y, z = atom.position
+        lines.append(f"{atom.symbol:<4s} {x:15.8f} {y:15.8f} {z:15.8f}")
+    return "\n".join(lines) + "\n"
+
+
+def from_xyz_string(content: str) -> Molecule:
+    """Parse a Molecule from an XYZ-format string.
+
+    Bonds are inferred from interatomic distances using covalent radii.
+    """
+    lines = content.strip().splitlines()
+    if len(lines) < 2:
+        raise ValueError("XYZ content must have at least two lines "
+                         "(atom count and comment).")
+
+    atom_count = int(lines[0].strip())
+    comment = lines[1].strip()
+
+    if len(lines) < atom_count + 2:
+        raise ValueError(f"XYZ file declares {atom_count} atoms but has only "
+                         f"{len(lines) - 2} atom lines")
+
+    mol = Molecule(name=comment)
+
+    for i in range(atom_count):
+        parts = lines[2 + i].split()
+        symbol = parts[0]
+        x, y, z = float(parts[1]), float(parts[2]), float(parts[3])
+        mol.add_atom(symbol, [x, y, z])
+
+    _infer_bonds(mol)
+    return mol
+
+
+# ── File I/O ──────────────────────────────────────────────────────────
+
+def write_xyz(mol: Molecule, filepath: str) -> None:
+    """Write a Molecule to an XYZ file."""
+    with open(filepath, "w") as f:
+        f.write(to_xyz_string(mol))
+
+
+def read_xyz(filepath: str) -> Molecule:
+    """Read a Molecule from an XYZ file.
+
+    Bonds are inferred from interatomic distances using covalent radii.
+    """
+    with open(filepath, "r") as f:
+        content = f.read()
+    return from_xyz_string(content)

molbuilder/molecule/__init__.py

@@ -0,0 +1,2 @@
+"""Molecule graph, conformations, and builders."""
+from molbuilder.molecule.graph import Molecule, Atom, Bond, Hybridization