molcrys-kit 0.3.0__py3-none-any.whl

molcrys_kit/__init__.py

@@ -0,0 +1,26 @@
+"""
+MolCrysKit: A Python toolkit for molecular crystal analysis and manipulation.
+
+This toolkit provides functionality for parsing, analyzing, and manipulating
+molecular crystal structures, with a particular focus on molecular crystals
+where well-defined molecules occupy crystallographic sites.
+"""
+
+__version__ = "0.3.0"
+
+from .structures.atom import MolAtom
+from .structures.molecule import CrystalMolecule
+from .structures.crystal import MolecularCrystal
+from .io.cif import read_mol_crystal
+
+# For backward compatibility
+Molecule = CrystalMolecule
+
+__all__ = [
+    "MolAtom",
+    "CrystalMolecule",
+    "MolecularCrystal",
+    "read_mol_crystal",
+    # Backward compatibility
+    "Molecule",
+]

molcrys_kit/analysis/__init__.py

@@ -0,0 +1,44 @@
+from .interactions import *
+from .species import *
+from .stoichiometry import *
+from .chemical_env import ChemicalEnvironment
+from .formula_moiety import Fragment, heavy_signature, match_molecule_to_fragment, parse_moiety_string
+from .charge import MolChargeResult, assign_mol_formal_charges, compute_topo_signature
+from .packing_shell import (
+    DEFAULT_CENTROID_OFFSET_FRAC,
+    DEFAULT_MOLECULAR_SEARCH_CUTOFF,
+    DEFAULT_POLYHEDRON_SEARCH_CUTOFF,
+    angular_rmsd_vs_ideals,
+    compute_angular_signature,
+    detect_coordination_number,
+    detect_prism_vs_antiprism,
+    find_polyhedra,
+    hull_encloses_center,
+    planarity_analysis,
+)
+from .shape import classify_shell, cshm, topology_signature
+
+
+__all__ = [
+    "ChemicalEnvironment",
+    "Fragment",
+    "MolChargeResult",
+    "DEFAULT_CENTROID_OFFSET_FRAC",
+    "DEFAULT_MOLECULAR_SEARCH_CUTOFF",
+    "DEFAULT_POLYHEDRON_SEARCH_CUTOFF",
+    "angular_rmsd_vs_ideals",
+    "assign_mol_formal_charges",
+    "classify_shell",
+    "compute_angular_signature",
+    "compute_topo_signature",
+    "cshm",
+    "heavy_signature",
+    "match_molecule_to_fragment",
+    "parse_moiety_string",
+    "detect_coordination_number",
+    "detect_prism_vs_antiprism",
+    "find_polyhedra",
+    "hull_encloses_center",
+    "planarity_analysis",
+    "topology_signature",
+]

molcrys_kit/analysis/charge.py

@@ -0,0 +1,183 @@
+"""
+Molecular formal charge determination for Tasker surface analysis.
+
+This module provides hybrid charge assignment for CrystalMolecule objects:
+  1. user-supplied mol_charge_map (formula → charge)
+  2. pymatgen BVAnalyzer auto-guess
+  3. zero fallback with warning
+"""
+
+import warnings
+import hashlib
+from dataclasses import dataclass
+from typing import Dict, List, Optional
+
+from ..structures.crystal import MolecularCrystal
+from ..structures.molecule import CrystalMolecule
+
+
+def compute_topo_signature(mol: CrystalMolecule) -> str:
+    """
+    Compute a topology signature for a molecule.
+
+    The signature combines the Hill-order chemical formula with a short hash
+    of the sorted node-degree sequence from the molecular connectivity graph,
+    making it sensitive to both composition and bond topology.
+
+    Parameters
+    ----------
+    mol : CrystalMolecule
+        Molecule to fingerprint.
+
+    Returns
+    -------
+    str
+        A string of the form "<formula>|<8-char hex hash>" that uniquely
+        identifies the molecule type within the crystal.
+    """
+    # Check cache first
+    if getattr(mol, '_topo_signature', None) is not None:
+        return mol._topo_signature
+    
+    formula = mol.get_chemical_formula(mode="hill", empirical=False)
+    graph = mol.get_graph()
+    degree_seq = sorted(d for _, d in graph.degree())
+    degree_hash = hashlib.md5(str(degree_seq).encode()).hexdigest()[:8]
+    sig = f"{formula}|{degree_hash}"
+    mol._topo_signature = sig
+    return sig
+
+
+@dataclass
+class MolChargeResult:
+    """
+    Formal charge assignment result for one distinct molecule topology.
+
+    Attributes
+    ----------
+    topo_signature : str
+        Topology signature (formula + degree-sequence hash).
+    formula : str
+        Hill-order chemical formula.
+    formal_charge : float
+        Assigned formal charge.
+    source : str
+        Origin of the charge value: "user_map", "auto_guess", or
+        "none" (zero fallback with warning).
+    """
+
+    topo_signature: str
+    formula: str
+    formal_charge: float
+    source: str  # "user_map" | "auto_guess" | "none"
+
+
+def _guess_charge_pymatgen(mol: CrystalMolecule) -> Optional[float]:
+    """
+    Attempt to guess the formal charge of a molecule using pymatgen BVAnalyzer.
+
+    The molecule is placed in a large cubic supercell (100 Å) to eliminate
+    spurious periodic interactions, then bond-valence analysis is applied.
+
+    Parameters
+    ----------
+    mol : CrystalMolecule
+        Molecule whose formal charge is to be guessed.
+
+    Returns
+    -------
+    float or None
+        Summed bond-valence oxidation states, or None on any failure.
+    """
+    try:
+        from pymatgen.core import Structure, Lattice
+        from pymatgen.analysis.bond_valence import BVAnalyzer
+
+        symbols = mol.get_chemical_symbols()
+        positions = mol.get_positions()
+        big_lattice = Lattice.cubic(100.0)
+        pmg_structure = Structure(
+            big_lattice,
+            species=symbols,
+            coords=positions,
+            coords_are_cartesian=True,
+        )
+        valences = BVAnalyzer().get_valences(pmg_structure)
+        return float(sum(valences))
+    except Exception:
+        return None
+
+
+def assign_mol_formal_charges(
+    crystal: MolecularCrystal,
+    mol_charge_map: Optional[Dict[str, int]] = None,
+) -> Dict[str, MolChargeResult]:
+    """
+    Assign formal charges to each distinct molecule topology in a crystal.
+
+    Uses a three-level hybrid strategy:
+
+    1. **user_map** – if mol_charge_map contains an entry for the
+       molecule formula, that value is used directly.
+    2. **auto_guess** – pymatgen :class: is used to estimate
+       bond-valence oxidation states, which are summed to give the molecular
+       formal charge.
+    3. **none** – if both methods fail, formal charge is set to 0 and a
+       :class: is emitted.  Downstream Tasker analysis will
+       degrade to topology-only ordering.
+
+    Parameters
+    ----------
+    crystal : MolecularCrystal
+        Crystal whose molecule population will be typed and charged.
+    mol_charge_map : dict, optional
+        Mapping from Hill-order chemical formula (e.g. "C8H9NO2") to
+        integer formal charge.
+
+    Returns
+    -------
+    dict
+        Mapping topo_signature -> MolChargeResult for every distinct
+        molecule topology found in *crystal*.  Multiple molecules sharing
+        the same topology contribute only one entry.
+    """
+    if mol_charge_map is None:
+        mol_charge_map = {}
+
+    results: Dict[str, MolChargeResult] = {}
+
+    for mol in crystal.molecules:
+        sig = compute_topo_signature(mol)
+        if sig in results:
+            continue
+
+        formula = mol.get_chemical_formula(mode="hill", empirical=False)
+
+        if formula in mol_charge_map:
+            charge = float(mol_charge_map[formula])
+            source = "user_map"
+        else:
+            guessed = _guess_charge_pymatgen(mol)
+            if guessed is not None:
+                charge = guessed
+                source = "auto_guess"
+            else:
+                charge = 0.0
+                source = "none"
+                warnings.warn(
+                    f"Could not determine formal charge for molecule ''{formula}''"
+                    f" (topo_signature='{sig}').  Defaulting to 0.  "
+                    "Tasker analysis will degrade to topology-only ordering.  "
+                    "Provide a mol_charge_map to suppress this warning.",
+                    UserWarning,
+                    stacklevel=2,
+                )
+
+        results[sig] = MolChargeResult(
+            topo_signature=sig,
+            formula=formula,
+            formal_charge=charge,
+            source=source,
+        )
+
+    return results