synkit 1.6.5__py3-none-win_amd64.whl

synkit/IO/data_io.py

@@ -0,0 +1,269 @@
+import os
+import json
+import pickle
+import numpy as np
+from numpy import ndarray
+from joblib import dump, load
+from typing import List, Dict, Any, Generator, Optional
+from synkit.IO.debug import setup_logging
+
+logger = setup_logging()
+
+
+def save_database(database: List[Dict], pathname: str = "./Data/database.json") -> None:
+    """Save a database (a list of dictionaries) to a JSON file.
+
+    :param database: The database to be saved.
+    :type database: list[dict]
+    :param pathname: The path where the database will be saved. Defaults
+        to './Data/database.json'.
+    :type pathname: str
+    :raises TypeError: If the database is not a list of dictionaries.
+    :raises ValueError: If there is an error writing the file.
+    """
+    if not all(isinstance(item, dict) for item in database):
+        raise TypeError("Database should be a list of dictionaries.")
+    try:
+        with open(pathname, "w") as f:
+            json.dump(database, f)
+    except IOError as e:
+        raise ValueError(f"Error writing to file {pathname}: {e}")
+
+
+def load_database(pathname: str = "./Data/database.json") -> List[Dict]:
+    """Load a database (a list of dictionaries) from a JSON file.
+
+    :param pathname: The path from where the database will be loaded.
+        Defaults to './Data/database.json'.
+    :type pathname: str
+    :return: The loaded database.
+    :rtype: list[dict]
+    :raises ValueError: If there is an error reading the file.
+    """
+    try:
+        with open(pathname, "r") as f:
+            database = json.load(f)
+        return database
+    except IOError as e:
+        raise ValueError(f"Error reading file {pathname}: {e}")
+
+
+def save_to_pickle(data: List[Dict[str, Any]], filename: str) -> None:
+    """Save a list of dictionaries to a pickle file.
+
+    :param data: A list of dictionaries to be saved.
+    :type data: list[dict]
+    :param filename: The name of the file where the data will be saved.
+    :type filename: str
+    """
+    with open(filename, "wb") as file:
+        pickle.dump(data, file)
+
+
+def load_from_pickle(filename: str) -> List[Any]:
+    """Load data from a pickle file.
+
+    :param filename: The name of the pickle file to load data from.
+    :type filename: str
+    :return: The data loaded from the pickle file.
+    :rtype: list
+    """
+    with open(filename, "rb") as file:
+        return pickle.load(file)
+
+
+def load_gml_as_text(gml_file_path: str) -> Optional[str]:
+    """Load the contents of a GML file as a text string.
+
+    :param gml_file_path: The file path to the GML file.
+    :type gml_file_path: str
+    :return: The text content of the GML file, or None if the file does
+        not exist or an error occurs.
+    :rtype: str or None
+    """
+    try:
+        with open(gml_file_path, "r") as file:
+            return file.read()
+    except FileNotFoundError:
+        logger.error(f"File not found: {gml_file_path}")
+        return None
+    except Exception as e:
+        logger.error(f"An error occurred while reading {gml_file_path}: {e}")
+        return None
+
+
+def save_text_as_gml(gml_text: str, file_path: str) -> bool:
+    """Save a GML text string to a file.
+
+    :param gml_text: The GML content as a text string.
+    :type gml_text: str
+    :param file_path: The file path where the GML text will be saved.
+    :type file_path: str
+    :return: True if saving was successful, False otherwise.
+    :rtype: bool
+    """
+    try:
+        with open(file_path, "w") as file:
+            file.write(gml_text)
+        logger.info(f"GML text successfully saved to {file_path}")
+        return True
+    except Exception as e:
+        logger.error(f"An error occurred while saving the GML text: {e}")
+        return False
+
+
+def save_compressed(array: ndarray, filename: str) -> None:
+    """Saves a NumPy array in a compressed format using .npz extension.
+
+    :param array: The NumPy array to be saved.
+    :type array: numpy.ndarray
+    :param filename: The file path or name to save the array to, with a
+        '.npz' extension.
+    :type filename: str
+    """
+    np.savez_compressed(filename, array=array)
+
+
+def load_compressed(filename: str) -> ndarray:
+    """Loads a NumPy array from a compressed .npz file.
+
+    :param filename: The path of the .npz file to load.
+    :type filename: str
+    :return: The loaded NumPy array.
+    :rtype: numpy.ndarray
+    :raises KeyError: If the .npz file does not contain an array with
+        the key 'array'.
+    """
+    with np.load(filename) as data:
+        if "array" in data:
+            return data["array"]
+        else:
+            raise KeyError(
+                "The .npz file does not contain an array with the key 'array'."
+            )
+
+
+def save_model(model: Any, filename: str) -> None:
+    """Save a machine learning model to a file using joblib.
+
+    :param model: The machine learning model to save.
+    :type model: object
+    :param filename: The path to the file where the model will be saved.
+    :type filename: str
+    """
+    dump(model, filename)
+    logger.info(f"Model saved successfully to {filename}")
+
+
+def load_model(filename: str) -> Any:
+    """Load a machine learning model from a file using joblib.
+
+    :param filename: The path to the file from which the model will be
+        loaded.
+    :type filename: str
+    :return: The loaded machine learning model.
+    :rtype: object
+    """
+    model = load(filename)
+    logger.info(f"Model loaded successfully from {filename}")
+    return model
+
+
+def save_dict_to_json(data: dict, file_path: str) -> None:
+    """Save a dictionary to a JSON file.
+
+    :param data: The dictionary to be saved.
+    :type data: dict
+    :param file_path: The path to the file where the dictionary should
+        be saved.
+    :type file_path: str
+    """
+    with open(file_path, "w") as json_file:
+        json.dump(data, json_file, indent=4)
+    logger.info(f"Dictionary successfully saved to {file_path}")
+
+
+def load_dict_from_json(file_path: str) -> Optional[dict]:
+    """Load a dictionary from a JSON file.
+
+    :param file_path: The path to the JSON file from which to load the
+        dictionary.
+    :type file_path: str
+    :return: The dictionary loaded from the JSON file, or None if an
+        error occurs.
+    :rtype: dict or None
+    """
+    try:
+        with open(file_path, "r") as json_file:
+            data = json.load(json_file)
+        logger.info(f"Dictionary successfully loaded from {file_path}")
+        return data
+    except Exception as e:
+        logger.error(e)
+        return None
+
+
+def load_from_pickle_generator(file_path: str) -> Generator[Any, None, None]:
+    """A generator that yields items from a pickle file where each pickle load
+    returns a list of dictionaries.
+
+    :param file_path: The path to the pickle file to load.
+    :type file_path: str
+    :yield: A single item from the list of dictionaries stored in the
+        pickle file.
+    :rtype: Any
+    """
+    with open(file_path, "rb") as file:
+        while True:
+            try:
+                batch_items = pickle.load(file)
+                for item in batch_items:
+                    yield item
+            except EOFError:
+                break
+
+
+def collect_data(num_batches: int, temp_dir: str, file_template: str) -> List[Any]:
+    """Collects and aggregates data from multiple pickle files into a single
+    list.
+
+    :param num_batches: The number of batch files to process.
+    :type num_batches: int
+    :param temp_dir: The directory where the batch files are stored.
+    :type temp_dir: str
+    :param file_template: The template string for batch file names,
+        expecting an integer formatter.
+    :type file_template: str
+    :return: A list of aggregated data items from all batch files.
+    :rtype: list
+    """
+    collected_data: List[Any] = []
+    for i in range(num_batches):
+        file_path = os.path.join(temp_dir, file_template.format(i))
+        for item in load_from_pickle_generator(file_path):
+            collected_data.append(item)
+    return collected_data
+
+
+def save_list_to_file(data_list: list, file_path: str) -> None:
+    """Save a list to a file in JSON format.
+
+    :param data_list: The list to save.
+    :type data_list: list
+    :param file_path: The path to the file where the list will be saved.
+    :type file_path: str
+    """
+    with open(file_path, "w") as file:
+        json.dump(data_list, file)
+
+
+def load_list_from_file(file_path: str) -> list:
+    """Load a list from a JSON-formatted file.
+
+    :param file_path: The path to the file to read the list from.
+    :type file_path: str
+    :return: The list loaded from the file.
+    :rtype: list
+    """
+    with open(file_path, "r") as file:
+        return json.load(file)

synkit/IO/data_process.py

@@ -0,0 +1,143 @@
+from typing import List, Dict, Any, Optional
+import joblib
+from tqdm import tqdm as _tqdm_type
+
+
+class TqdmJoblib:
+    """
+    Context manager to integrate a tqdm progress bar with joblib's Parallel.
+
+    Usage:
+        with TqdmJoblib(tqdm(total=100)) as t:
+            Parallel(...)(delayed(...)(...) for ...)
+
+    :param tqdm_obj: an instantiated tqdm progress bar object (e.g. `tqdm(total=...)`).
+    :type tqdm_obj: tqdm.tqdm
+    :param max_batch_size: maximum sensible batch size to accept from joblib's
+                           callback; anything larger will be treated as 1 to avoid
+                           corrupting the bar.
+    :type max_batch_size: int, optional
+    :param allow_overshoot: if False (default) cap updates so the bar never
+                            exceeds `tqdm_obj.total`. If True, allow normal updates.
+    :type allow_overshoot: bool, optional
+    :param silent_close_errors: swallow exceptions raised when closing the tqdm
+                                object on exit (default True).
+    :type silent_close_errors: bool, optional
+    :raises AttributeError: if joblib has no `parallel.BatchCompletionCallBack`.
+    """
+
+    def __init__(
+        self,
+        tqdm_obj: _tqdm_type,
+        max_batch_size: int = 10**6,
+        allow_overshoot: bool = False,
+        silent_close_errors: bool = True,
+    ) -> None:
+        self.tqdm_obj = tqdm_obj
+        self.max_batch_size = int(max_batch_size)
+        self.allow_overshoot = bool(allow_overshoot)
+        self.silent_close_errors = bool(silent_close_errors)
+
+        self._orig: Optional[Any] = None
+        self._patched = False
+
+    def __enter__(self):
+        orig_cb = getattr(joblib.parallel, "BatchCompletionCallBack", None)
+        if orig_cb is None:
+            raise AttributeError("joblib.parallel.BatchCompletionCallBack not found")
+
+        self._orig = orig_cb
+
+        def _callback(*args, **kwargs):
+            try:
+                n = int(args[0])
+                if n <= 0 or n > self.max_batch_size:
+                    raise ValueError
+            except Exception:
+                n = 1
+
+            if not self.allow_overshoot:
+                remaining = max(0, (self.tqdm_obj.total or 0) - (self.tqdm_obj.n or 0))
+                inc = n if n <= remaining else remaining
+            else:
+                inc = n
+
+            if inc > 0:
+                try:
+                    self.tqdm_obj.update(inc)
+                except Exception:
+                    # If tqdm object's update fails for any reason, fallback to +1
+                    try:
+                        self.tqdm_obj.update(1)
+                    except Exception:
+                        pass
+
+            return self._orig(*args, **kwargs)
+
+        joblib.parallel.BatchCompletionCallBack = _callback
+        self._patched = True
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if self._patched and self._orig is not None:
+            try:
+                joblib.parallel.BatchCompletionCallBack = self._orig
+            except Exception:
+                # best-effort restore; ignore to avoid masking user exceptions
+                pass
+
+        try:
+            if self.tqdm_obj is not None:
+                self.tqdm_obj.close()
+        except Exception:
+            if not self.silent_close_errors:
+                raise
+
+
+def merge_dicts(
+    list1: List[Dict[str, Any]],
+    list2: List[Dict[str, Any]],
+    key: str,
+    intersection: bool = True,
+) -> List[Dict[str, Any]]:
+    """Merges two lists of dictionaries based on a specified key, with an
+    option to either merge only dictionaries with matching key values
+    (intersection) or all dictionaries (union).
+
+    :param list1: The first list of dictionaries.
+    :type list1: List[Dict[str, Any]]
+    :param list2: The second list of dictionaries.
+    :type list2: List[Dict[str, Any]]
+    :param key: The key used to match and merge dictionaries from both lists.
+    :type key: str
+    :param intersection: If True, only merge dictionaries with matching key values;
+                         if False, merge all dictionaries, combining those with matching key values.
+    :type intersection: bool
+
+    :return: Dictionaries merged according to the selected strategy.
+    :rtype: List[Dict[str, Any]]
+    """
+    dict1 = {item[key]: item for item in list1}
+    dict2 = {item[key]: item for item in list2}
+
+    if intersection:
+        # Intersection of keys: only keys present in both dictionaries are merged
+        merged_list = []
+        for item1 in list1:
+            r_id = item1.get(key)
+            if r_id in dict2:
+                merged_item = {**item1, **dict2[r_id]}
+                merged_list.append(merged_item)
+        return merged_list
+    else:
+        # Union of keys: all keys from both dictionaries are merged
+        merged_dict = {}
+        all_keys = set(dict1) | set(dict2)
+        for k in all_keys:
+            if k in dict1 and k in dict2:
+                merged_dict[k] = {**dict1[k], **dict2[k]}
+            elif k in dict1:
+                merged_dict[k] = dict1[k]
+            else:
+                merged_dict[k] = dict2[k]
+        return list(merged_dict.values())

synkit/IO/debug.py

@@ -0,0 +1,73 @@
+import os
+import logging
+import warnings
+from rdkit import rdBase, RDLogger
+
+
+def setup_logging(
+    log_level: str = "INFO", log_filename: str = None, task_type: str = None
+) -> logging.Logger:
+    """Configures logging to either the console or a file, based on provided
+    parameters.
+
+    :param log_level: Logging level to set. Defaults to 'INFO'.
+                      Options: 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'.
+    :type log_level: str
+    :param log_filename: If provided, logs are written to this file. Defaults to None (logs to console).
+    :type log_filename: str or None
+    :param task_type: Logger name/namespace. Useful for distinguishing loggers in multi-task settings.
+                     Defaults to None.
+    :type task_type: str or None
+
+    :return: Configured logger instance.
+    :rtype: logging.Logger
+
+    :raises ValueError: If an invalid log level is provided.
+    """
+    log_format = "%(asctime)s - %(levelname)s - %(message)s"
+    numeric_level = getattr(logging, log_level.upper(), None)
+
+    if not isinstance(numeric_level, int):
+        raise ValueError(f"Invalid log level: {log_level}")
+
+    logger = logging.getLogger(task_type)
+    logger.handlers.clear()  # Efficiently remove all existing handlers
+
+    if log_filename:
+        os.makedirs(os.path.dirname(log_filename), exist_ok=True)
+        logging.basicConfig(
+            level=numeric_level, format=log_format, filename=log_filename, filemode="a"
+        )
+    else:
+        logging.basicConfig(level=numeric_level, format=log_format)
+
+    return logger
+
+
+def configure_warnings_and_logs(
+    ignore_warnings: bool = False, disable_rdkit_logs: bool = False
+) -> None:
+    """Configures Python warnings and RDKit log behavior based on input flags.
+
+    :param ignore_warnings: Whether to suppress all Python warnings.
+        Default is False.
+    :type ignore_warnings: bool
+    :param disable_rdkit_logs: Whether to disable RDKit error and
+        warning logs. Default is False.
+    :type disable_rdkit_logs: bool
+    :return: None :usage: Use this function to control verbosity (e.g.
+        in production or testing), but use with caution during
+        development to avoid missing critical issues.
+    """
+    if ignore_warnings:
+        warnings.filterwarnings("ignore")
+    else:
+        warnings.resetwarnings()
+
+    if disable_rdkit_logs:
+        rdBase.DisableLog("rdApp.error")
+        rdBase.DisableLog("rdApp.warning")
+        RDLogger.DisableLog("rdApp.warning")
+    else:
+        rdBase.EnableLog("rdApp.error")
+        rdBase.EnableLog("rdApp.warning")

synkit/IO/gml_to_nx.py

@@ -0,0 +1,150 @@
+import re
+import networkx as nx
+from typing import Tuple
+from synkit.Graph.ITS.its_construction import ITSConstruction
+
+
+class GMLToNX:
+    """Parses GML-like text and transforms it into three NetworkX graphs
+    representing the left, right, and context graphs of a chemical reaction
+    step.
+
+    :param gml_text: The GML-like text to parse.
+    :type gml_text: str
+    :ivar graphs: A dictionary containing 'left', 'right', and 'context'
+        NetworkX graphs.
+    :vartype graphs: dict[str, nx.Graph]
+    """
+
+    def __init__(self, gml_text: str):
+        """Initializes a GMLToNX object that can parse GML-like text into
+        separate NetworkX graphs representing different stages or components of
+        a chemical reaction.
+
+        :param gml_text: The GML-like text to be parsed.
+        :type gml_text: str
+        """
+        self.gml_text = gml_text
+        self.graphs = {"left": nx.Graph(), "context": nx.Graph(), "right": nx.Graph()}
+
+    def _parse_element(self, line: str, current_section: str):
+        """Parses a line of GML-like text to extract node or edge data and adds
+        it to the current section's graph.
+
+        :param line: A single line of GML-like text.
+        :type line: str
+        :param current_section: Which section ('left', 'right',
+            'context') to add the node/edge to.
+        :type current_section: str
+        """
+        label_to_order = {"-": 1, ":": 1.5, "=": 2, "#": 3}
+        tokens = line.split()
+
+        if "node" in line:
+            node_id = int(tokens[tokens.index("id") + 1])
+            label = tokens[tokens.index("label") + 1].strip('"')
+            element, charge = self._extract_element_and_charge(label)
+            node_attributes = {
+                "element": element,
+                "charge": charge,
+                "atom_map": node_id,
+                "hcount": 0,
+            }
+            self.graphs[current_section].add_node(node_id, **node_attributes)
+
+        elif "edge" in line:
+            source = int(tokens[tokens.index("source") + 1])
+            target = int(tokens[tokens.index("target") + 1])
+            label = tokens[tokens.index("label") + 1].strip('"')
+            order = label_to_order.get(label, 0)
+            self.graphs[current_section].add_edge(source, target, order=order)
+
+    def _extract_element_and_charge(self, label: str) -> Tuple[str, int]:
+        """Extracts the chemical element and its charge from a node label.
+
+        :param label: The label string from a GML node (e.g., 'N+',
+            'O2-', etc.).
+        :type label: str
+        :return: A tuple of (element symbol, formal charge).
+        :rtype: tuple[str, int]
+        """
+        match = re.match(r"([A-Za-z*]+)(\d+)?([+-])?$", label)
+        if not match:
+            return ("X", 0)
+        element = match.group(1)
+        num = match.group(2)
+        sign = match.group(3)
+        charge = 0
+        if sign:
+            charge_val = int(num) if num else 1
+            charge = charge_val if sign == "+" else -charge_val
+        return element, charge
+
+    def _synchronize_nodes_and_edges(self):
+        """Ensures that all nodes and edges in 'context' appear in both 'left'
+        and 'right'. We do not remove edges from left or right if they are not
+        in context. We only add missing context nodes and edges to left and
+        right.
+
+        :return: None
+        """
+        # Add missing context nodes to left and right
+        for node, ndata in self.graphs["context"].nodes(data=True):
+            if node not in self.graphs["left"]:
+                self.graphs["left"].add_node(node, **ndata)
+            else:
+                # Merge attributes if node already exists in left
+                for k, v in ndata.items():
+                    self.graphs["left"].nodes[node][k] = v
+
+            if node not in self.graphs["right"]:
+                self.graphs["right"].add_node(node, **ndata)
+            else:
+                # Merge attributes if node already exists in right
+                for k, v in ndata.items():
+                    self.graphs["right"].nodes[node][k] = v
+
+        # Add missing context edges to left and right
+        for s, t, edata in self.graphs["context"].edges(data=True):
+            if not self.graphs["left"].has_edge(s, t):
+                self.graphs["left"].add_edge(s, t, **edata)
+            if not self.graphs["right"].has_edge(s, t):
+                self.graphs["right"].add_edge(s, t, **edata)
+
+    def transform(self) -> Tuple[nx.Graph, nx.Graph, nx.Graph]:
+        """Transforms the GML-like text into three NetworkX graphs: left, right, and context.
+
+        :return: A tuple of (left_graph, right_graph, context_graph), each a NetworkX graph.
+        :rtype: tuple[nx.Graph, nx.Graph, nx.Graph]
+        """
+        current_section = None
+        lines = self.gml_text.split("\n")
+        for line in lines:
+            line = line.strip()
+            if line.startswith("rule") or line == "]":
+                continue
+            if any(section in line for section in ["left", "context", "right"]):
+                current_section = line.split("[")[0].strip()
+                continue
+            if line.startswith("node") or line.startswith("edge"):
+                self._parse_element(line, current_section)
+
+        # Synchronize after parsing
+        self._synchronize_nodes_and_edges()
+
+        # Create the ITS graph
+        its_graph = ITSConstruction().ITSGraph(
+            self.graphs["left"], self.graphs["right"]
+        )
+
+        # Restore node attributes in ITS graph from left (or right)
+        for n in its_graph.nodes():
+            if n in self.graphs["left"].nodes:
+                for k, v in self.graphs["left"].nodes[n].items():
+                    its_graph.nodes[n][k] = v
+
+        self.graphs["context"] = ITSConstruction().ITSGraph(
+            self.graphs["left"], self.graphs["right"]
+        )
+
+        return self.graphs["left"], self.graphs["right"], self.graphs["context"]