synkit 1.6.5__py3-none-win_amd64.whl

synkit/IO/nx_to_gml.py

@@ -0,0 +1,209 @@
+import networkx as nx
+from typing import Tuple, List
+
+
+class NXToGML:
+    """Converts NetworkX graph representations of chemical reactions to GML
+    (Graph Modelling Language) strings. Useful for exporting reaction rules in
+    a standard graph format.
+
+    This class provides static methods for converting individual graphs,
+    sets of reaction graphs, and managing charge/attribute changes in
+    the export process.
+    """
+
+    def __init__(self) -> None:
+        """Initializes an NXToGML object."""
+        pass
+
+    @staticmethod
+    def _charge_to_string(charge: int) -> str:
+        """Converts an integer charge into a string representation.
+
+        :param charge: The charge value, which can be positive,
+            negative, or zero.
+        :type charge: int
+        :return: The string representation of the charge (e.g. '+',
+            '2+', '-', '3-', '').
+        :rtype: str
+        """
+        if charge > 0:
+            return "+" if charge == 1 else f"{charge}+"
+        elif charge < 0:
+            return "-" if charge == -1 else f"{-charge}-"
+        else:
+            return ""
+
+    @staticmethod
+    def _find_changed_nodes(
+        graph1: nx.Graph, graph2: nx.Graph, attributes: List[str] = ["charge"]
+    ) -> List[int]:
+        """Identifies nodes with changes in specified attributes between two
+        NetworkX graphs.
+
+        :param graph1: The first NetworkX graph.
+        :type graph1: nx.Graph
+        :param graph2: The second NetworkX graph.
+        :type graph2: nx.Graph
+        :param attributes: List of attribute names to check for changes.
+        :type attributes: list[str]
+        :return: Node identifiers that have changes in the specified
+            attributes.
+        :rtype: list[int]
+        """
+        changed_nodes = []
+        for node in graph1.nodes():
+            if node in graph2:
+                for attr in attributes:
+                    value1 = graph1.nodes[node].get(attr, None)
+                    value2 = graph2.nodes[node].get(attr, None)
+                    if value1 != value2:
+                        changed_nodes.append(node)
+                        break
+        return changed_nodes
+
+    @staticmethod
+    def _convert_graph_to_gml(
+        graph: nx.Graph,
+        section: str,
+        changed_node_ids: List[int],
+        explicit_hydrogen: bool = False,
+    ) -> str:
+        """Converts a NetworkX graph to a GML string for a specific reaction
+        section.
+
+        :param graph: The NetworkX graph to be converted.
+        :type graph: nx.Graph
+        :param section: The section name in the GML output ('left',
+            'right', or 'context').
+        :type section: str
+        :param changed_node_ids: List of nodes with changed attributes.
+        :type changed_node_ids: list[int]
+        :param explicit_hydrogen: Whether to explicitly include hydrogen
+            atoms in the output.
+        :type explicit_hydrogen: bool
+        :return: The GML string representation of the graph for the
+            specified section.
+        :rtype: str
+        """
+        order_to_label = {1: "-", 1.5: ":", 2: "=", 3: "#"}
+        gml_str = f"   {section} [\n"
+
+        if section == "context":
+            for node in graph.nodes(data=True):
+                if node[0] not in changed_node_ids:
+                    element = node[1].get("element", "X")
+                    charge = node[1].get("charge", 0)
+                    charge_str = NXToGML._charge_to_string(charge)
+                    gml_str += (
+                        f'      node [ id {node[0]} label "{element}{charge_str}" ]\n'
+                    )
+            if explicit_hydrogen:
+                for edge in graph.edges(data=True):
+                    order = edge[2].get("order", (1.0, 1.0))
+                    standard_order = edge[2].get("standard_order", (0))
+                    if standard_order == 0:
+                        label = order_to_label.get(order, "-")
+                        gml_str += (
+                            f"      edge [ source {edge[0]} target {edge[1]}"
+                            + f' label "{label}" ]\n'
+                        )
+
+        if section != "context":
+            for edge in graph.edges(data=True):
+                label = order_to_label.get(edge[2].get("order", 1), "-")
+                gml_str += f'      edge [ source {edge[0]} target {edge[1]} label "{label}" ]\n'
+            for node in graph.nodes(data=True):
+                if node[0] in changed_node_ids:
+                    element = node[1].get("element", "X")
+                    charge = node[1].get("charge", 0)
+                    charge_str = NXToGML._charge_to_string(charge)
+                    gml_str += (
+                        f'      node [ id {node[0]} label "{element}{charge_str}" ]\n'
+                    )
+
+        gml_str += "   ]\n"
+        return gml_str
+
+    @staticmethod
+    def _rule_grammar(
+        L: nx.Graph,
+        R: nx.Graph,
+        K: nx.Graph,
+        rule_name: str,
+        changed_node_ids: List[int],
+        explicit_hydrogen: bool,
+    ) -> str:
+        """Generates a GML string for a chemical rule, including left, context,
+        and right graphs.
+
+        :param L: The left graph.
+        :type L: nx.Graph
+        :param R: The right graph.
+        :type R: nx.Graph
+        :param K: The context graph.
+        :type K: nx.Graph
+        :param rule_name: The name of the rule.
+        :type rule_name: str
+        :param changed_node_ids: List of nodes with changed attributes.
+        :type changed_node_ids: list[int]
+        :param explicit_hydrogen: Whether to explicitly include hydrogen
+            atoms in the output.
+        :type explicit_hydrogen: bool
+        :return: The GML string representation of the rule.
+        :rtype: str
+        """
+        gml_str = "rule [\n"
+        gml_str += f'   ruleID "{rule_name}"\n'
+        gml_str += NXToGML._convert_graph_to_gml(L, "left", changed_node_ids)
+        gml_str += NXToGML._convert_graph_to_gml(
+            K, "context", changed_node_ids, explicit_hydrogen
+        )
+        gml_str += NXToGML._convert_graph_to_gml(R, "right", changed_node_ids)
+        gml_str += "]"
+        return gml_str
+
+    @staticmethod
+    def transform(
+        graph_rules: Tuple[nx.Graph, nx.Graph, nx.Graph],
+        rule_name: str = "Test",
+        reindex: bool = False,
+        attributes: List[str] = ["charge"],
+        explicit_hydrogen: bool = False,
+    ) -> str:
+        """Processes a triple of reaction graphs to generate a GML string rule,
+        with options for node reindexing and explicit hydrogen expansion.
+
+        :param graph_rules: Tuple containing (L, R, K) reaction graphs.
+        :type graph_rules: tuple[nx.Graph, nx.Graph, nx.Graph]
+        :param rule_name: The rule name to use in the output.
+        :type rule_name: str
+        :param reindex: Whether to reindex node IDs based on the L graph
+            sequence.
+        :type reindex: bool
+        :param attributes: List of attribute names to check for node
+            changes.
+        :type attributes: list[str]
+        :param explicit_hydrogen: Whether to explicitly include hydrogen
+            atoms in the output.
+        :type explicit_hydrogen: bool
+        :return: The GML string representing the chemical rule.
+        :rtype: str
+        """
+        L, R, K = graph_rules
+        if explicit_hydrogen:
+            from synkit.Graph.Hyrogen._misc import h_to_explicit
+
+            K = h_to_explicit(K, nodes=None)
+        if reindex:
+            index_mapping = {
+                old_id: new_id for new_id, old_id in enumerate(L.nodes(), 1)
+            }
+            L = nx.relabel_nodes(L, index_mapping)
+            R = nx.relabel_nodes(R, index_mapping)
+            K = nx.relabel_nodes(K, index_mapping)
+        changed_node_ids = NXToGML._find_changed_nodes(L, R, attributes)
+        rule_grammar = NXToGML._rule_grammar(
+            L, R, K, rule_name, changed_node_ids, explicit_hydrogen
+        )
+        return rule_grammar

synkit/IO/smiles_to_id.py

@@ -0,0 +1,123 @@
+import time
+import requests
+import urllib.parse
+from typing import List
+from joblib import Parallel, delayed
+
+
+def smiles_to_iupac(smiles_string: str, timeout: int = 1):
+    """Converts a SMILES string to its corresponding IUPAC name(s) using the
+    PubChem PUG REST API.
+
+    :param smiles_string: The SMILES string of the compound (e.g., "C=O" for formaldehyde).
+    :type smiles_string: str
+    :param timeout: The timeout in seconds for the request. Default is 1 second.
+    :type timeout: int, optional
+
+    :return: A list of IUPAC names associated with the SMILES string. Returns an empty list if none found.
+    :rtype: list
+    """
+    # URL encode the SMILES string to handle special characters
+    encoded_smiles = urllib.parse.quote(smiles_string)
+
+    # PubChem PUG REST API endpoint to retrieve properties
+    url = f"https://pubchem.ncbi.nlm.nih.gov/rest/pug/compound/smiles/{encoded_smiles}/property/IUPACName/JSON"
+
+    retries = 3  # Number of retries in case of failure
+    delay = 2  # Delay between retries (in seconds)
+
+    for attempt in range(retries):
+        try:
+            response = requests.get(url, timeout=timeout)  # Adjust timeout for speed
+            response.raise_for_status()  # Raise an HTTPError for bad responses
+
+            data = response.json()
+
+            # Extract the IUPAC name(s) from the response
+            properties = data.get("PropertyTable", {}).get("Properties", [])
+
+            if not properties:
+                print(f"No properties found for SMILES: {smiles_string}")
+                return []
+
+            iupac_names = [
+                prop.get("IUPACName") for prop in properties if prop.get("IUPACName")
+            ]
+
+            if iupac_names:
+                return iupac_names
+            else:
+                print(f"No IUPAC name found for SMILES: {smiles_string}")
+                return []
+
+        except (requests.exceptions.RequestException, ValueError, KeyError) as e:
+            # If an error occurs, retry a few times
+            print(
+                f"Attempt {attempt + 1} failed for SMILES: {smiles_string}, Error: {e}"
+            )
+            if attempt < retries - 1:
+                time.sleep(delay)  # Wait before retrying
+            else:
+                print(f"Final failure for SMILES: {smiles_string}")
+                return []
+
+    return []
+
+
+def batch_process_smiles(smiles_batch: List[str], timeout=1):
+    """Processes a batch of SMILES strings to get IUPAC names.
+
+    :param smiles_batch: A list of SMILES strings to process.
+    :type smiles_batch: list
+    :param timeout: Timeout for requests (in seconds).
+    :type timeout: int
+
+    :return: A list of IUPAC name results for each SMILES in the batch.
+    :rtype: list
+    """
+    return [smiles_to_iupac(smiles, timeout) for smiles in smiles_batch]
+
+
+def get_iupac_for_smiles_list(
+    smiles_list: List[str], batch_size=10, n_jobs=4, timeout=1
+):
+    """Convert a list of SMILES strings to their corresponding IUPAC names
+    using the PubChem API with batch processing.
+
+    :param smiles_list: A list of SMILES strings to be converted to IUPAC names.
+    :type smiles_list: list
+    :param batch_size: Number of SMILES strings to process in each batch.
+    :type batch_size: int
+    :param n_jobs: Number of parallel jobs to run for batch processing.
+    :type n_jobs: int
+    :param timeout: Timeout for requests (in seconds).
+    :type timeout: int
+
+    :return: A dictionary with SMILES as keys and lists of IUPAC names as values.
+    :rtype: dict
+    """
+    # Split the list into smaller batches
+    # fmt: off
+    batches = [
+        smiles_list[i: i + batch_size] for i in range(0, len(smiles_list), batch_size)
+    ]
+    # fmt: on
+
+    # Use joblib's Parallel and delayed to process batches in parallel
+    batch_results = Parallel(n_jobs=n_jobs)(
+        delayed(batch_process_smiles)(batch, timeout) for batch in batches
+    )
+
+    # Flatten the list of results and map to SMILES
+    flattened_results = [item for sublist in batch_results for item in sublist]
+    iupac_dict = dict(zip(smiles_list, flattened_results))
+
+    return iupac_dict
+
+
+# Example of usage
+smiles_list = ["CCO", "C=O", "CC(=O)O", "C1=CC=CC=C1", "C2H6O", "C4H10", "C5H12"]
+iupac_results = get_iupac_for_smiles_list(smiles_list, batch_size=3, n_jobs=2)
+
+for smiles, iupac_names in iupac_results.items():
+    print(f"SMILES: {smiles} => IUPAC Names: {iupac_names}")

synkit/Mechanism/__init__.py

@@ -0,0 +1,151 @@
+"""Public v2 models for representing supplied reaction mechanisms."""
+
+from .adapters import (
+    electron_move_from_legacy_epd,
+    group_from_legacy_epd,
+    legacy_epd_from_group,
+    mechanism_from_ef_smirks,
+    mechanism_from_legacy_epd,
+)
+from .audit import (
+    LocalElectronStateAudit,
+    RadicalStateAudit,
+    audit_local_electron_state,
+    radical_counts_by_atom_map,
+    radical_match,
+)
+from .compatibility import (
+    COMPATIBLE_LEWIS_GRAPH_ACRONYMS,
+    LEGACY_LEWIS_GRAPH_ACRONYM,
+    PREVIOUS_PUBLIC_LEWIS_GRAPH_ACRONYM,
+    PUBLIC_LEWIS_GRAPH_ACRONYM,
+    PUBLIC_LEWIS_GRAPH_NAME,
+)
+from .model import (
+    SCHEMA_VERSION,
+    ElectronLocus,
+    ElectronMove,
+    ElectronMoveGroup,
+    ElectrocyclicStereoMotion,
+    MechanismModelError,
+    MechanismRecord,
+    MechanisticStep,
+    StereoDescriptor,
+    StereoEffect,
+    VerificationCertificate,
+    VerificationIssue,
+)
+from .neighbor_stereo import RelativeNeighborChange
+from .schema import mechanism_record_schema
+from .equivalence import mechanism_equivalent
+from .interchange import (
+    ConversionLossReport,
+    project_record,
+    project_stereo_graph,
+    stereo_graph_from_gml,
+    stereo_graph_to_gml,
+)
+from .stereo_state import (
+    StereoStateTimeline,
+    apply_stereo_effects,
+    stereo_timeline,
+)
+from .benchmark import (
+    BenchmarkCase,
+    CorruptedAnnotation,
+    benchmark_release_issues,
+    corrupt_record,
+    radical_candidates,
+    write_candidate_manifest,
+)
+from .radical_data import (
+    RADICAL_CLASS_TO_MACRO,
+    RadicalAAMCompletionResult,
+    RadicalDatasetRecord,
+    RadicalNormalizationReport,
+    complete_radical_aam,
+    iter_radical_csv,
+    normalize_radical_row,
+    radical_dataset_summary,
+)
+from .replay import (
+    GroupReplayReport,
+    MechanismReplayer,
+    MechanismReplayResult,
+)
+from .symbols import (
+    LONE_PAIR,
+    PI,
+    RADICAL,
+    SIGMA,
+    external_locus_symbol,
+    internal_action_label,
+    legacy_action_label,
+    normalize_locus_symbol,
+)
+
+__all__ = [
+    "SCHEMA_VERSION",
+    "ElectronLocus",
+    "ElectronMove",
+    "ElectronMoveGroup",
+    "ElectrocyclicStereoMotion",
+    "MechanismModelError",
+    "MechanismRecord",
+    "MechanisticStep",
+    "StereoDescriptor",
+    "StereoEffect",
+    "VerificationCertificate",
+    "VerificationIssue",
+    "RelativeNeighborChange",
+    "RadicalStateAudit",
+    "LocalElectronStateAudit",
+    "audit_local_electron_state",
+    "PUBLIC_LEWIS_GRAPH_NAME",
+    "PUBLIC_LEWIS_GRAPH_ACRONYM",
+    "PREVIOUS_PUBLIC_LEWIS_GRAPH_ACRONYM",
+    "LEGACY_LEWIS_GRAPH_ACRONYM",
+    "COMPATIBLE_LEWIS_GRAPH_ACRONYMS",
+    "radical_counts_by_atom_map",
+    "radical_match",
+    "electron_move_from_legacy_epd",
+    "group_from_legacy_epd",
+    "legacy_epd_from_group",
+    "mechanism_from_ef_smirks",
+    "mechanism_from_legacy_epd",
+    "mechanism_record_schema",
+    "LONE_PAIR",
+    "SIGMA",
+    "PI",
+    "RADICAL",
+    "normalize_locus_symbol",
+    "external_locus_symbol",
+    "internal_action_label",
+    "legacy_action_label",
+    "RADICAL_CLASS_TO_MACRO",
+    "RadicalAAMCompletionResult",
+    "RadicalDatasetRecord",
+    "RadicalNormalizationReport",
+    "complete_radical_aam",
+    "normalize_radical_row",
+    "iter_radical_csv",
+    "radical_dataset_summary",
+    "GroupReplayReport",
+    "MechanismReplayer",
+    "MechanismReplayResult",
+    "mechanism_equivalent",
+    "ConversionLossReport",
+    "project_record",
+    "project_stereo_graph",
+    "stereo_graph_from_gml",
+    "stereo_graph_to_gml",
+    "apply_stereo_effects",
+    "stereo_timeline",
+    "StereoStateTimeline",
+    "BenchmarkCase",
+    "CorruptedAnnotation",
+    "benchmark_release_issues",
+    "corrupt_record",
+    "radical_candidates",
+    "write_candidate_manifest",
+]

synkit/Mechanism/adapters.py

@@ -0,0 +1,136 @@
+"""Compatibility adapters between v1 EPD/EF-SMIRKS and v2 models."""
+
+from __future__ import annotations
+
+from typing import Any, Iterable, Sequence
+
+from .model import (
+    ElectronLocus,
+    ElectronMove,
+    ElectronMoveGroup,
+    MechanismModelError,
+    MechanismRecord,
+    MechanisticStep,
+)
+from .symbols import legacy_action_label, normalize_locus_symbol
+
+_ACTION_LOCI = {
+    "LP": "lp",
+    "RAD": "∙",
+    "SIGMA": "σ",
+    "PI": "π",
+}
+
+
+def _locus(token: str, atom_maps: Sequence[int]) -> ElectronLocus:
+    kind = _ACTION_LOCI.get(token.strip().upper())
+    if kind is None:
+        if token.strip().upper() == "B":
+            raise MechanismModelError(
+                "Generic legacy 'B' does not identify σ versus π; use typed "
+                "EPD or an ITS-aware adapter."
+            )
+        try:
+            kind = normalize_locus_symbol(token)
+        except (TypeError, ValueError) as exc:
+            raise MechanismModelError(
+                f"Unsupported legacy EPD locus: {token!r}"
+            ) from exc
+    return ElectronLocus(kind=kind, atom_maps=tuple(int(value) for value in atom_maps))
+
+
+def electron_move_from_legacy_epd(
+    row: Sequence[Any], *, group_id: str = "g1", event_id: str | None = None
+) -> ElectronMove:
+    """Losslessly adapt one polar v1 ``[action, source, target]`` row."""
+    if len(row) < 3:
+        raise MechanismModelError(f"Invalid legacy EPD row: {row!r}")
+    action, source, target = row[:3]
+    try:
+        source_token, target_token = str(action).split("-/", 1)
+        target_token = target_token.removesuffix("+")
+    except ValueError as exc:
+        raise MechanismModelError(f"Invalid legacy EPD action: {action!r}") from exc
+    return ElectronMove(
+        event_id=event_id,
+        source=_locus(source_token, source),
+        target=_locus(target_token, target),
+        electron_count=2,
+        arrow_type="curved",
+        group_id=group_id,
+        metadata={"legacy_action": str(action)},
+    )
+
+
+def group_from_legacy_epd(
+    epd: Iterable[Sequence[Any]], *, group_id: str = "g1"
+) -> ElectronMoveGroup:
+    moves = tuple(
+        electron_move_from_legacy_epd(row, group_id=group_id, event_id=f"e{index}")
+        for index, row in enumerate(epd, start=1)
+    )
+    return ElectronMoveGroup(group_id=group_id, moves=moves)
+
+
+def mechanism_from_legacy_epd(
+    mapped_reaction: str,
+    epd: Iterable[Sequence[Any]],
+    *,
+    provenance: dict[str, Any] | None = None,
+) -> MechanismRecord:
+    # Legacy EPD is an ordered list of local edits.  Preserve that ordering by
+    # giving every row its own step/group; callers can explicitly coalesce
+    # events when they have simultaneous-event provenance.
+    steps = tuple(
+        MechanisticStep(
+            step_id=f"s{index}",
+            groups=(
+                ElectronMoveGroup(
+                    group_id=f"g{index}",
+                    moves=(
+                        electron_move_from_legacy_epd(
+                            row, group_id=f"g{index}", event_id=f"e{index}"
+                        ),
+                    ),
+                ),
+            ),
+        )
+        for index, row in enumerate(epd, start=1)
+    )
+    return MechanismRecord(
+        mapped_reaction=mapped_reaction,
+        steps=steps,
+        provenance={"format": "legacy_epd", **(provenance or {})},
+    )
+
+
+def mechanism_from_ef_smirks(text: str, **kwargs: Any) -> MechanismRecord:
+    """Create a v2 record from existing EF-SMIRKS conversion support.
+
+    EF-SMIRKS currently encodes legacy two-electron arrow geometry only;
+    fishhook metadata is represented directly by :class:`ElectronMove`.
+    """
+    from synkit.Graph.Mech.conversion import ef_smirks_to_epd
+
+    converted = ef_smirks_to_epd(text, **kwargs)
+    return mechanism_from_legacy_epd(
+        converted["complete_aam"],
+        converted["epd_lw"],
+        provenance={"format": "ef_smirks", "ef_smirks": text},
+    )
+
+
+def legacy_epd_from_group(group: ElectronMoveGroup) -> list[list[Any]]:
+    """Return v1 rows when all moves are representable polar curved arrows."""
+    rows: list[list[Any]] = []
+    for move in group.moves:
+        if move.electron_count != 2:
+            raise MechanismModelError("Fishhooks cannot be represented by legacy EPD.")
+        rows.append(
+            [
+                legacy_action_label(move.source.kind, move.target.kind),
+                list(move.source.atom_maps),
+                list(move.target.atom_maps),
+            ]
+        )
+    return rows