From df8b5ca27d60ae6d64ac6035636a80e4265a007d Mon Sep 17 00:00:00 2001
From: Alex Moldovan
Date: Tue, 17 Nov 2026 12:35:42 +0000
Subject: [PATCH] Initial Commit of Simplifier NO_JIRA
---
scripts/ReadMe.md | 1 +
scripts/core/simplifier/define_simplifier.py | 28 +
scripts/core/simplifier/readme.md | 113 +++
scripts/core/simplifier/simplifier.py | 647 ++++++++++++++++++
scripts/core/simplifier/tests/ABABEL.mol2 | 72 ++
.../core/simplifier/tests/test_simplifier.py | 642 +++++++++++++++++
scripts/core/simplifier/use_simplifier.py | 22 +
.../use_simplifier_remove_unmatched.py | 21 +
8 files changed, 1546 insertions(+)
create mode 100644 scripts/core/simplifier/define_simplifier.py
create mode 100644 scripts/core/simplifier/readme.md
create mode 100644 scripts/core/simplifier/simplifier.py
create mode 100644 scripts/core/simplifier/tests/ABABEL.mol2
create mode 100644 scripts/core/simplifier/tests/test_simplifier.py
create mode 100644 scripts/core/simplifier/use_simplifier.py
create mode 100644 scripts/core/simplifier/use_simplifier_remove_unmatched.py
diff --git a/scripts/ReadMe.md b/scripts/ReadMe.md
index 53731f0..48e379c 100644
--- a/scripts/ReadMe.md
+++ b/scripts/ReadMe.md
@@ -24,6 +24,7 @@ Various scripts with no specific licence requirements that may be useful for a v
| Refcodes With Properties | A script for generating refcode lists with specific properties from an easy-to-read control file. |
| Show semiconductor properties | Displays semiconductor properties for the structure currently loaded in Mercury. |
| Void Search | A script to search on pre-calculated Void properties. |
+| Simplifier | Simplify molecular complexity by creating skeletal frames. Works in Mercury and CLI. Information in the publication "Simplifying crystal structures: a new tool for visualising packing motifs in molecular crystals as skeletal frameworks" DOI: |
## Discovery
diff --git a/scripts/core/simplifier/define_simplifier.py b/scripts/core/simplifier/define_simplifier.py
new file mode 100644
index 0000000..a52d539
--- /dev/null
+++ b/scripts/core/simplifier/define_simplifier.py
@@ -0,0 +1,28 @@
+#
+# This script can be used for any purpose without limitation subject to the
+# conditions at http://www.ccdc.cam.ac.uk/Community/Pages/Licences/v2.aspx
+#
+# This permission notice and the following statement of attribution must be
+# included in all copies or substantial portions of this script.
+#
+# 2024-07-26 Created by Chris Kingsbury, the Cambridge Crystallographic Data Centre
+# ORCID 0000-0002-4694-5566
+# 2024-10-30 Modified by Alex Moldovan, the Cambridge Crystallographic Data Centre
+# flake8: noqa
+import sys
+from simplifier import MercuryInterface
+
+import numpy as np
+
+if __name__ == "__main__":
+ if len(sys.argv) > 3 and sys.argv[3].endswith(".m2a"):
+ mercury_interface = MercuryInterface()
+ if not mercury_interface.write_readme_if_none_selected():
+ atom_clicking_order = np.argsort(np.argsort(mercury_interface.interface.selected_indices))
+ selected_atoms_in_order = [mercury_interface.interface.selected_atoms[x] for x in atom_clicking_order]
+ mercury_interface.simplifier.define_simplification(crystal=mercury_interface.crystal,
+ user_selected_atoms=selected_atoms_in_order)
+ mercury_interface.simplifier.use_simplification(mercury_interface.crystal)
+ mercury_interface.write_output()
+ else:
+ raise NotImplementedError("Implementation is for Mercury - CSD Python API menu only")
diff --git a/scripts/core/simplifier/readme.md b/scripts/core/simplifier/readme.md
new file mode 100644
index 0000000..ece5700
--- /dev/null
+++ b/scripts/core/simplifier/readme.md
@@ -0,0 +1,113 @@
+# Simplifier
+
+A molecular simplifier, akin to a "ribbon"-type protein representation, designed to run inside the Mercury CSD Python API menu or from the command line.
+
+`Simplifier` takes a set of user-selected atoms in a molecule and creates a reusable SMARTS simplification rule and connectivity skeleton. This rule can then be applied to any crystal structure
+containing the same molecular substructure (such as polymorphs, solvates/hydrates, salts, or co-crystals) to replace the full molecule with a simplified skeletal representation.
+
+Information in the publication along with a set of guidelines in the supporting information "Simplifying crystal structures: a new tool for visualising packing motifs in molecular crystals as skeletal frameworks" DOI:
+
+## Setup in Mercury
+
+1. Place the `simplifier` folder in a location where you have read/write permissions.
+2. Open the latest version of **Mercury**, select **CSD Python API** in the top toolbar, and click **Options...**.
+3. Under **Additional Mercury Script Locations**, click **Add Location**, select the parent folder that contains the `simplifier` directory, and click **Save**.
+4. In the **CSD Python API** menu in Mercury, you will now see **simplifier** as a submenu containing `define_simplifier.py`, `use_simplifier.py`, and `use_simplifier_remove_unmatched.py`. We
+ recommend starting with `define_simplifier.py`.
+
+## Mercury Workflow
+
+### 1. Defining a Simplification Rule (`define_simplifier.py`)
+
+1. Load a crystal structure in Mercury.
+2. Select **between 2 and 10 atoms** belonging to the molecule you want to simplify:
+ - **Important**: You must select **more than 1 atom** (at least 2 atoms, up to a maximum of 10 atoms). If 0 or 1 atom is selected when running `define_simplifier.py`, this README will be displayed
+ in the Mercury HTML report instead.
+ - For **2 selected atoms**, a single connecting edge (`0-1`) is created between them.
+ - For **3 to 10 selected atoms**, connectivity is automatically determined using the shortest topological path distances across the molecule in the order the atoms were clicked.
+3. Run **CSD Python API > simplifier > define_simplifier.py**.
+4. Mercury will:
+ - Generate an atom-mapped SMARTS string and connectivity string and store them in the cache (`simplifier_data.json`).
+ - Replace the matched molecules in the current view with their simplified skeletal representation.
+ - Open an HTML report displaying the SMARTS string, the connectivity pairs, a 2D chemical diagram highlighting the mapped atoms (`:0`, `:1`, ...), and the path to the cache file.
+
+### 2. Using a Simplification Rule (`use_simplifier.py` / `use_simplifier_remove_unmatched.py`)
+
+Once a molecule's simplification rule has been defined and cached, open another structure containing the same substructure (e.g., another polymorph, hydrate, salt, or co-crystal):
+
+- **`use_simplifier.py`**: Replaces matched molecules with their simplified skeleton while **keeping unmatched components** (such as solvent molecules, counterions, or co-formers) intact.
+- **`use_simplifier_remove_unmatched.py`**: Replaces matched molecules with their simplified skeleton and **removes all unmatched components** from the output structure.
+
+## Command-Line Interface (CLI) Usage
+
+`simplifier.py` can also be run directly from the command line using the CSD Python API environment:
+
+```bash
+python simplifier.py [options]
+```
+
+### CLI Arguments
+
+| Argument | Description |
+|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `idents` | One or more CSD refcodes (e.g., `HXACAN28`), structure files (`.cif`, `.mol2`), a `.gcd` refcode list file, or `cwd` to process all `.cif`/`.mol2` files in the current working directory. |
+| `-s`, `--smarts` | Override the SMARTS simplification string (defaults to the first matching entry found in `simplifier_data.json`). |
+| `-c`, `--connectivity` | Override the connectivity string (e.g., `011223`). Defaults to the cached connectivity or sequential chain connectivity. |
+| `-od`, `--output_directory` | Directory to write simplified output structures (`_s.` and `combined.mol2`). Defaults to the current working directory. |
+| `-ff`, `--file_format` | Output file format for individual simplified structures (default: `mol2`). |
+| `-p`, `--parameters` | Path to a JSON file containing CLI parameter overrides. |
+| `-v`, `--verbose` | Print progress for each structure processed. |
+| `-rm`, `--remove_unmatched` | Remove unmatched molecular components from the simplified crystal structure. |
+| `-ma`, `--match_all` | Match each molecule independently rather than using the same SMARTS for all. |
+| `-as`, `--add_smarts` | Add a SMARTS rule (`ident` + `-s ` + optional `-c `) directly to `simplifier_data.json` and exit. |
+| `-sd`, `--simplifier_data` | Path to the `simplifier_data.json` cache file (defaults to `simplifier_data.json` in the `simplifier` script directory). |
+
+### CLI Examples
+
+Simplify a CSD entry using existing cached rules and write outputs to `./out`:
+
+```bash
+python simplifier.py HXACAN28 -od ./out -v
+```
+
+Simplify all `.cif` and `.mol2` files in the current directory and remove unmatched solvent molecules:
+
+```bash
+python simplifier.py cwd -rm
+```
+
+Add a custom SMARTS simplification rule and connectivity to the cache file:
+
+```bash
+python simplifier.py HYQUIN08 -as -s "[#8H:0]c1ccc([#8H:1])cc1" -c "01"
+```
+
+## Cache Storage (`simplifier_data.json`)
+
+- **In Mercury**: `MercuryInterface` stores the cache at `/../../simplifier_cache/simplifier_data.json` so that rules defined in one Mercury session remain accessible across
+ different structures and runs.
+- **In the CLI**: Defaults to `scripts/simplifier/simplifier_data.json` unless overridden with `-sd` / `--simplifier_data`.
+- **Privacy Note**: `simplifier_data.json` contains SMARTS/SMILES strings for structures you have defined. Do not share this file between organisations if it contains proprietary chemical structures.
+
+## Files
+
+- `simplifier.py`: Core library (`Simplifier`, `SimplifierData`, `MercuryInterface`) and command-line interface.
+- `define_simplifier.py`: Mercury entry point to define a new simplification rule from selected atoms (2 to 10 atoms).
+- `use_simplifier.py`: Mercury entry point to apply a cached simplification rule while retaining unmatched molecules.
+- `use_simplifier_remove_unmatched.py`: Mercury entry point to apply a cached simplification rule and delete unmatched molecules.
+- `simplifier_data.json`: JSON cache storing `smiles` (SMARTS) and `connectivity` mappings keyed by structure identifier.
+- `tests/test_simplifier.py`: Unit test suite covering `SimplifierData`, `Simplifier`, CLI options, and `MercuryInterface`.
+
+## Running Unit Tests
+
+Run the unit test suite using the CSD Python API Python environment:
+
+```bash
+python -m unittest discover -s scripts/simplifier/tests -v
+```
+
+## Author
+
+Chris Kingsbury and Alex Moldovan, CCDC (2024)
+
+For feedback or to report any issues please contact [support@ccdc.cam.ac.uk](mailto:support@ccdc.cam.ac.uk)
diff --git a/scripts/core/simplifier/simplifier.py b/scripts/core/simplifier/simplifier.py
new file mode 100644
index 0000000..68b927e
--- /dev/null
+++ b/scripts/core/simplifier/simplifier.py
@@ -0,0 +1,647 @@
+#
+# This script can be used for any purpose without limitation subject to the
+# conditions at http://www.ccdc.cam.ac.uk/Community/Pages/Licences/v2.aspx
+#
+# This permission notice and the following statement of attribution must be
+# included in all copies or substantial portions of this script.
+#
+# 2024-04-08 Created by Chris Kingsbury, the Cambridge Crystallographic Data Centre
+# 2026-10-21 Update to public version (Chris Kingsbury, Alex Moldovan)
+# ORCID 0000-0002-4694-5566
+#
+# ccdc-licence-features not applicable
+# flake8: noqa
+from pathlib import Path
+
+import base64
+import ccdc.diagram
+import ccdc.io
+import ccdc.molecule
+import ccdc.search
+import dataclasses
+import io
+import itertools
+import json
+import numpy as np
+import os
+import re
+import warnings
+from ccdc.utilities import ApplicationInterface
+from copy import copy
+from dataclasses import dataclass, field
+from typing import TypeVar, List, Dict, Union
+
+Molecule = TypeVar('Molecule')
+Crystal = TypeVar('Crystal')
+Atom = TypeVar('Atom')
+Entry = TypeVar('Entry')
+Connectivity = TypeVar('Connectivity')
+
+
+class NothingToSmileAbout(Exception):
+ pass
+
+
+def markdown_to_html(md_text: str) -> str:
+ """Convert Markdown text to HTML, using the markdown package if installed or a built-in fallback."""
+ try:
+ import markdown
+
+ return markdown.markdown(md_text, extensions=["tables", "fenced_code"])
+ except ImportError:
+ import html
+
+ lines = md_text.splitlines()
+ out = []
+ in_code = False
+ in_list = None
+ in_table = False
+
+ def format_inline(text: str) -> str:
+ escaped = html.escape(text)
+ escaped = re.sub(r"\[([^\]]+)\]\(([^)]+)\)", r'\1', escaped)
+ escaped = re.sub(r"\*\*([^*]+)\*\*", r"\1", escaped)
+ escaped = re.sub(r"`([^`]+)`", r"\1", escaped)
+ return escaped
+
+ def close_blocks():
+ nonlocal in_list, in_table
+ if in_list:
+ out.append(f"{in_list}>")
+ in_list = None
+ if in_table:
+ out.append("")
+ in_table = False
+
+ for line in lines:
+ stripped = line.strip()
+ if stripped.startswith("```"):
+ close_blocks()
+ if not in_code:
+ out.append("")
+ in_code = True
+ else:
+ out.append("
")
+ in_code = False
+ continue
+
+ if in_code:
+ out.append(html.escape(line))
+ continue
+
+ if not stripped:
+ close_blocks()
+ continue
+
+ header_match = re.match(r"^(#{1,6})\s+(.*)$", stripped)
+ if header_match:
+ close_blocks()
+ level = len(header_match.group(1))
+ title = header_match.group(2)
+ slug = re.sub(r"[^a-z0-9]+", "-", title.lower()).strip("-")
+ out.append(f'{format_inline(title)}')
+ continue
+
+ if stripped.startswith("|") and stripped.endswith("|"):
+ cells = [c.strip() for c in stripped.strip("|").split("|")]
+ if all(re.match(r"^:?-+:?$", c) for c in cells):
+ continue
+ if not in_table:
+ close_blocks()
+ out.append("")
+ for cell in cells:
+ out.append(f"| {format_inline(cell)} | ")
+ out.append("
")
+ in_table = True
+ else:
+ out.append("")
+ for cell in cells:
+ out.append(f"| {format_inline(cell)} | ")
+ out.append("
")
+ continue
+
+ ul_match = re.match(r"^[-*]\s+(.*)$", stripped)
+ if ul_match:
+ if in_table:
+ out.append("
")
+ in_table = False
+ if in_list != "ul":
+ if in_list:
+ out.append(f"{in_list}>")
+ out.append("")
+ in_list = "ul"
+ out.append(f"- {format_inline(ul_match.group(1))}
")
+ continue
+
+ ol_match = re.match(r"^\d+\.\s+(.*)$", stripped)
+ if ol_match:
+ if in_table:
+ out.append("")
+ in_table = False
+ if in_list != "ol":
+ if in_list:
+ out.append(f"{in_list}>")
+ out.append("")
+ in_list = "ol"
+ out.append(f"- {format_inline(ol_match.group(1))}
")
+ continue
+
+ close_blocks()
+ out.append(f"{format_inline(stripped)}
")
+
+ if in_code:
+ out.append("")
+ close_blocks()
+ return "\n".join(out)
+
+
+class MercuryInterface:
+
+ def __init__(self, leave_unmatched_molecules: bool = False):
+ warnings.filterwarnings("ignore", category=DeprecationWarning)
+ self.interface = ApplicationInterface(parse_commandline=False)
+ self.interface.parse_commandline()
+ try:
+ self.crystal = self.interface.current_entry.crystal
+ except OSError:
+ self.crystal = ccdc.io.CrystalReader(self.interface.input_mol2_file).__next__()
+ self.crystal.molecule.assign_bonds()
+ # This essentially puts the cache in a folder that lives in the user documents along with the ref code
+ # folders so it's visible by all runs
+ simplifier_cache_folder = Path(self.interface.working_directory_path).parents[2] / "simplifier_cache"
+ if not os.path.isdir(simplifier_cache_folder):
+ os.mkdir(simplifier_cache_folder)
+ simplifier_cache_file = os.path.join(simplifier_cache_folder, "simplifier_data.json")
+ self.simplifier = Simplifier(data_path=simplifier_cache_file,
+ leave_unmatched_molecules=leave_unmatched_molecules)
+
+ def write_output(self):
+ self.simplifier.write_output(interface=self.interface)
+ self.simplifier.write_output_molecule(file_output=self.interface.output_mol2_file,
+ crystal=self.crystal)
+
+ def write_readme_if_none_selected(self):
+ if len(self.interface.selected_atoms) <= 1:
+ readme_md = (Path(__file__).parent / "readme.md").read_text(encoding="utf-8")
+ readme_html = markdown_to_html(readme_md)
+ Path(self.interface.output_html_file).write_text(readme_html, encoding="utf-8")
+ return True
+ else:
+ return False
+
+
+@dataclass
+class SimplifierData:
+ cache_storage: Path
+ smiles: Dict = field(default_factory=dict)
+ connectivity: Dict = field(default_factory=dict)
+
+ def __post_init__(self):
+ if isinstance(self.cache_storage, str):
+ self.cache_storage = Path(self.cache_storage)
+
+ self._loaded_from_file = False
+ if not self.cache_storage.parent.is_dir():
+ raise NotADirectoryError(f'{self.cache_storage} Does not have a valid directory')
+ if len(self.smiles.keys()) == 0:
+ if self.cache_storage.is_file() and (len(self.cache_storage.read_text()) > 1):
+ self.load_from_file()
+ else:
+ self.write_cache_storage()
+
+ def load_from_file(self):
+ if not self.cache_storage.is_file():
+ raise FileNotFoundError(f"Could not find the cache file for the simplifier data in {self.cache_storage}")
+ with open(self.cache_storage, "r") as f:
+ raw_data = json.load(f)
+ self.smiles = raw_data['smiles']
+ self.connectivity = raw_data['connectivity']
+
+ def write_cache_storage(self):
+ with open(self.cache_storage, "w") as file:
+ safe_dict = {k: v for k, v in dataclasses.asdict(self).items() if k not in ("cache_storage")}
+ file.write(json.dumps(safe_dict, separators=(", \n", ": ")))
+
+ def update_data(self, identifier: str, smiles: str, connectivity: str) -> None:
+ self.smiles.update({identifier: smiles})
+ self.connectivity.update({identifier: connectivity})
+ self.write_cache_storage()
+
+
+class Simplifier:
+ def __init__(self, data_path: Union[str, Path] = None, leave_unmatched_molecules: bool = True):
+ self._selected_molecule = None
+ self._selected_smiles = None
+ self._connectivity = None
+ self.simplifier_data = SimplifierData(cache_storage=data_path)
+ self.leave_unmatched_molecules = leave_unmatched_molecules
+
+ @property
+ def selected_smiles(self) -> str:
+ if self._selected_smiles:
+ return self._selected_smiles
+
+ @selected_smiles.setter
+ def selected_smiles(self, value: str):
+ self._selected_smiles = value
+
+ @property
+ def connectivity(self) -> str:
+ if self._connectivity:
+ return self._connectivity
+
+ @connectivity.setter
+ def connectivity(self, value: str):
+ self._connectivity = value
+
+ @property
+ def selected_molecule(self) -> Molecule:
+ if self._selected_molecule:
+ return self._selected_molecule
+
+ @selected_molecule.setter
+ def selected_molecule(self, value: Molecule):
+ self._selected_molecule = value
+
+ def get_selected_atoms_and_connectivity(self, user_selected_atoms: List[object]) -> tuple[List[Atom], Connectivity]:
+ if not 2 <= len(user_selected_atoms) <= 10:
+ raise ValueError("Please select between 2 and 10 atoms")
+ self._selected_molecule.assign_bond_types(which="unknown")
+ self._selected_molecule = [
+ x for x in self._selected_molecule.components if user_selected_atoms[0] in x.atoms
+ ][0]
+ selected_atoms_labels = [x.label for x in user_selected_atoms]
+ selected_atoms = [self._selected_molecule.atom(x) for x in selected_atoms_labels]
+ if len(selected_atoms) > 2:
+ distances = np.array(
+ [
+ [self._selected_molecule.shortest_path(at1, at2) for at2 in selected_atoms]
+ for at1 in selected_atoms
+ ]
+ )
+ selected_atoms, connectivity = self.optimise_association_matrix_with_connectivity(distances, selected_atoms,
+ iterations=10)
+ elif len(selected_atoms) == 2:
+ connectivity = '01'
+ else:
+ raise ValueError("Please select more than one atom")
+ return selected_atoms, connectivity
+
+ @staticmethod
+ def optimise_association_matrix_with_connectivity(distances: np.ndarray,
+ selected_atoms: List[Atom],
+ iterations: int = 10,
+ branching=True) -> tuple[List[Atom], Connectivity]:
+ if not branching:
+ for _ in range(iterations):
+ total_distance = np.sum(np.diagonal(distances, 1))
+ for i, j in itertools.combinations(range(len(selected_atoms)), 2):
+ if np.sum(np.diagonal(swap_two(distances, i, j), 1)) < total_distance:
+ selected_atoms[i], selected_atoms[j] = (
+ selected_atoms[j],
+ selected_atoms[i],
+ )
+ distances = swap_two(distances, i, j)
+ connectivity = ''.join([f"{i}{i + 1}" for i in range(len(selected_atoms) - 1)])
+ else:
+ connectivity = '01' + ''.join(
+ [f"{int(np.argmin(row[:row_ix]))}{row_ix}" for row_ix, row in enumerate(distances) if row_ix > 1])
+
+ return selected_atoms, connectivity
+
+ @staticmethod
+ def alter_molecule_smiles(selected_atoms: List[Atom], molecule: Molecule) -> str:
+ original_atomic_numbers = [x.atomic_number for x in selected_atoms]
+ repl_list = ["Lr", "Rf", "Db", "Sg", "Bh", "Hs", "Mt", "Ds", "Rg", "Cn"]
+
+ for atom, repl in zip(selected_atoms, repl_list):
+ atom.atomic_symbol = repl
+
+ smiles_altered = molecule.smiles
+ pattern = re.compile("|".join([f"\\[{Xx}?.?.?.?.\\]" for Xx in repl_list]))
+
+ keys = pattern.findall(smiles_altered)
+
+ for key in keys:
+ atom_sym = key[1:3]
+ if "H" in key:
+ extras = key[3:][:-1]
+ else:
+ extras = ""
+ try:
+ ind = repl_list.index(atom_sym)
+ except ValueError:
+ continue
+ smiles_altered = smiles_altered.replace(
+ key, f"[#{original_atomic_numbers[ind]}{extras}:{ind}]"
+ )
+ return smiles_altered
+
+ def get_smarts(self, output_crystal: Crystal) -> str:
+ for refcode, stored_smiles in self.simplifier_data.smiles.items():
+ smarts = ccdc.search.SMARTSSubstructure(stored_smiles)
+ self.selected_smiles = None
+ if smarts.match_molecule(output_crystal.molecule):
+ print(f"Found {refcode}")
+ self._selected_smiles = stored_smiles
+ self._connectivity = self.simplifier_data.connectivity.get(refcode, None)
+ break
+ if self.selected_smiles is None:
+ raise NothingToSmileAbout("No smiles found in dictionary.")
+ return smarts
+
+ def use_simplification(self, crystal: Crystal, smarts: object = None, connectivity: object = None):
+ molecule = crystal.molecule
+ molecule.assign_bond_types(which="unknown")
+ crystal.molecule = molecule
+
+ output_crystal = copy(crystal)
+ self._selected_molecule = output_crystal.molecule
+ if smarts is None:
+ smarts = self.get_smarts(output_crystal)
+ elif isinstance(smarts, str):
+ self._selected_smiles = smarts
+ smarts = ccdc.search.SMARTSSubstructure(smarts)
+ elif hasattr(smarts, "smarts"):
+ self._selected_smiles = smarts.smarts
+
+ if connectivity is None:
+ connectivity = self._connectivity
+ else:
+ self._connectivity = connectivity
+ sss = ccdc.search.SubstructureSearch()
+ sss.add_substructure(smarts)
+
+ slabs = [i for i in range(10) if f":{i}" in self._selected_smiles]
+ indices = [smarts.label_to_atom_index(str(i)) for i in slabs]
+
+ if not connectivity:
+ for i, (a, b) in enumerate(zip(indices[1:], indices)):
+ sss.add_vector(f"vec{i}", (0, a), (0, b))
+ number_of_bonds = len(indices) - 1
+ else:
+ for i, (a, b) in enumerate(zip(connectivity[::2], connectivity[1::2])):
+ sss.add_vector(f"vec{i}", (0, indices[int(a)]), (0, indices[int(b)]))
+ number_of_bonds = len(connectivity[::2])
+
+ hits = sss.search(output_crystal)
+ simple_labels = set()
+
+ for hit in hits:
+ for i in range(number_of_bonds):
+ at_a_l, at_b_l = [x.label for x in hit.vector_atoms(f"vec{i}")]
+ at_a, at_b = [self._selected_molecule.atom(x) for x in (at_a_l, at_b_l)]
+ simple_labels.update({at_a_l, at_b_l})
+ if at_a not in at_b.neighbours:
+ self._selected_molecule.add_bond(1, at_a, at_b)
+
+ if self.leave_unmatched_molecules:
+ remove_labels = set()
+ for comp in self._selected_molecule.components:
+ if len([x for x in comp.atoms if (x.label in simple_labels)]) > 0:
+ remove_labels.update(
+ {x.label for x in comp.atoms if x.label not in simple_labels}
+ )
+ self._selected_molecule.remove_atoms([x for x in self._selected_molecule.atoms if x.label in remove_labels])
+ else:
+ self._selected_molecule.remove_atoms(
+ [x for x in self._selected_molecule.atoms if x.label not in simple_labels])
+
+ def define_simplification(self, crystal: Crystal, user_selected_atoms: List[Atom]) -> None:
+ identifier = crystal.identifier
+ self._selected_molecule = crystal.molecule
+ selected_atoms, self._connectivity = self.get_selected_atoms_and_connectivity(user_selected_atoms)
+
+ self.selected_smiles = self.alter_molecule_smiles(selected_atoms, self._selected_molecule)
+ print(self._selected_smiles)
+
+ self.simplifier_data.update_data(identifier, self._selected_smiles, self._connectivity)
+
+ def simplification_diagram(self):
+ dg = ccdc.diagram.DiagramGenerator()
+
+ smarts = ccdc.search.SMARTSSubstructure(self._selected_smiles)
+ slabs = [i for i in range(10) if f":{i}" in self._selected_smiles]
+ indices = [smarts.label_to_atom_index(str(i)) for i in slabs]
+
+ cleaned_smiles = self._selected_smiles.replace('~', '')
+ mol = ccdc.molecule.Molecule.from_string(cleaned_smiles)
+
+ hats = [x for i, x in enumerate(mol.atoms) if i in indices]
+ for i, x in zip(np.argsort(indices), hats):
+ x.label = x.label + f":{i}"
+
+ with io.BytesIO() as buf:
+ dg.image(mol, hats, label_atoms=hats).save(buf, 'png')
+ image_base64 = base64.b64encode(buf.getvalue()).decode('utf-8').replace('\n', '')
+
+ self.simplification_image_html = f'
'
+ return self.simplification_image_html
+
+ def connectivity_typog(self):
+ if not self.connectivity:
+ return None
+ return ', '.join([f"{a}-{b}" for a, b in zip(self.connectivity[::2], self.connectivity[1::2])])
+
+ def write_output(self, interface: ApplicationInterface, smiles_altered: str = None) -> None:
+ if smiles_altered is None:
+ smiles_altered = self.selected_smiles
+ with interface.html_report(title=f"smiles for {interface.identifier}") as report:
+ report.write(
+ f'{smiles_altered}
'
+ )
+ report.write(
+ f''' Connectivity: {self.connectivity_typog()}
'''
+ )
+ report.write(
+ self.simplification_diagram()
+ )
+ report.write(
+ f''' Simplifier Cache Storage: {self.simplifier_data.cache_storage}
'''
+ )
+
+ def write_output_molecule(self, file_output: str, crystal: Crystal) -> None:
+ with ccdc.io.CrystalWriter(file_output) as crystal_writer:
+ crystal.molecule = self._selected_molecule
+ crystal_writer.write(crystal)
+
+
+# swaps the rows and columns of an array to a new array. Useful for
+# substitution of two nodes in an association matrix
+def swap_two(arr, i, j):
+ A = arr.copy()
+ A[[i, j], :] = A[[j, i], :]
+ A[:, [i, j]] = A[:, [j, i]]
+ return A
+
+
+# Gets the relevant arguments for the simplifier to the command line or in Prototypes
+def get_args():
+ import argparse
+
+ parser = argparse.ArgumentParser()
+
+ parser.add_argument(
+ "idents",
+ type=str,
+ nargs="+",
+ help="the files/refcodes that will be analysed (or .gcd)",
+ )
+
+ parser.add_argument(
+ "-s",
+ "--smarts",
+ type=str,
+ default=None,
+ help="override SMARTS simplification string - default is first found in simplifier_data.json",
+ )
+
+ parser.add_argument(
+ "-c",
+ "--connectivity",
+ type=str,
+ default=None,
+ help="override connectivity - default is first found in simplifier_data.json",
+ )
+
+ parser.add_argument(
+ "-od",
+ "--output_directory",
+ type=str,
+ default=None,
+ help="put outputs in this directory",
+ )
+ parser.add_argument(
+ "-ff",
+ "--file_format",
+ type=str,
+ default="mol2",
+ help="file format for output",
+ )
+
+ parser.add_argument(
+ "-p",
+ "--parameters",
+ type=str,
+ default=None,
+ help="parameters from JSON",
+ )
+
+ parser.add_argument("-v", "--verbose", action="store_true", help="print as you go")
+
+ parser.add_argument(
+ "-rm",
+ "--remove_unmatched",
+ action="store_true",
+ help="remove unmatched molecules",
+ )
+ parser.add_argument(
+ "-ma",
+ "--match_all",
+ action="store_true",
+ help="match each molecule independently (instead of using the same SMARTS for all)",
+ )
+
+ parser.add_argument(
+ "-as",
+ "--add_smarts",
+ action="store_true",
+ help="add a smarts string to the json (as ident:smarts) and then quit",
+ )
+ parser.add_argument(
+ '-sd',
+ '--simplifier_data',
+ default=f'{os.path.join(os.path.abspath(os.path.dirname(__file__)), "simplifier_data.json")}',
+ help="Provide the location of the simplifier data cache. Default with CMD is the script location"
+ )
+ args = parser.parse_args()
+ return args
+
+
+def simplifier_cl(settings=None):
+ args = get_args()
+ simplify = Simplifier(data_path=args.simplifier_data, leave_unmatched_molecules=not args.remove_unmatched)
+
+ if args.parameters:
+ import json
+
+ with open(args.parameters, "rt") as f:
+ jsondict = json.load(f)
+ args.__dict__.update(jsondict)
+ if settings:
+ args.__dict__.update(settings)
+
+ if args.add_smarts:
+ smarts_val = getattr(args, "smiles", None) or args.smarts
+ simplify.selected_smiles = smarts_val
+ if args.connectivity:
+ simplify.connectivity = args.connectivity
+ else:
+ simplify.connectivity = "".join([f"{ix}{ix + 1}" for ix in range(smarts_val.count(":") - 1)])
+ simplify.simplifier_data.update_data(args.idents[0], simplify._selected_smiles, simplify._connectivity)
+ print(f"added {args.idents[0]}: {smarts_val}")
+ return None
+
+ if "." not in "".join(args.idents):
+ csd_reader = ccdc.io.CrystalReader("CSD")
+
+ if args.idents[0] == "cwd":
+ directory = Path(os.getcwd())
+ args.idents = [
+ str(directory / filenm)
+ for filenm in list(directory.iterdir())
+ if filenm.suffix in [".cif", ".mol2"]
+ ]
+
+ if args.idents[0].endswith(".gcd"):
+ csd_reader = ccdc.io.CrystalReader("CSD")
+ refcodes = open(args.idents[0], "r").readlines()
+ args.idents = [
+ x.rstrip("\n") for x in refcodes if len(x.rstrip("\n")) in [6, 8]
+ ]
+
+ for index, ident in enumerate(args.idents):
+ if args.verbose:
+ print(f"{ident} ({index + 1} / {len(args.idents)})")
+
+ if "." in ident:
+ source = ccdc.io.CrystalReader(ident)[0]
+ else:
+ source = csd_reader.crystal(ident.upper())
+ if len(source.molecule.atoms) < 1:
+ warnings.warn(f"{ident} has no atoms that are viable for this tool")
+ continue
+ output = copy(source)
+ print(source.identifier)
+ try:
+ if args.smarts:
+ simplify.selected_smiles = args.smarts
+ smarts = ccdc.search.SMARTSSubstructure(args.smarts)
+ if args.connectivity:
+ connectivity = args.connectivity
+ else:
+ connectivity = "".join([f"{ix}{ix+1}" for ix in range(simplify.selected_smiles.count(":")-1)])
+ simplify.use_simplification(crystal=source, smarts=smarts, connectivity=connectivity)
+ else:
+ simplify.use_simplification(crystal=source)
+ except NothingToSmileAbout:
+ warnings.warn(f"{ident} has no smiles stored in cache. Please use mercury and inspect your structure.")
+ continue
+ filenm = f"{Path(ident).stem}_s.{args.file_format}"
+ output_molecule = str(Path(args.output_directory or os.getcwd()) / filenm)
+ simplify.write_output_molecule(file_output=output_molecule, crystal=output)
+
+ with open(
+ str(Path(args.output_directory or os.getcwd()) / "combined.mol2"), "w"
+ ) as outfile:
+ for index, ident in enumerate(args.idents):
+ filenm = f"{Path(ident).stem}_s.{args.file_format}"
+ filepath = Path(args.output_directory or os.getcwd()) / filenm
+ if os.path.isfile(filepath):
+ with open(filepath, "r") as fob:
+ outfile.write(fob.read())
+ outfile.write("\n\n")
+
+
+if __name__ == "__main__":
+ simplifier_cl()
diff --git a/scripts/core/simplifier/tests/ABABEL.mol2 b/scripts/core/simplifier/tests/ABABEL.mol2
new file mode 100644
index 0000000..1cfed60
--- /dev/null
+++ b/scripts/core/simplifier/tests/ABABEL.mol2
@@ -0,0 +1,72 @@
+@MOLECULE
+ABABEL
+ 28 30 1 0 0
+SMALL
+NO_CHARGES
+****
+Generated from the CSD
+
+@ATOM
+ 1 Cl1 7.3346 7.6453 10.4450 Cl 1 RES1 0.0000
+ 2 O1 8.8526 3.4719 8.0722 O.2 1 RES1 0.0000
+ 3 N1 10.4173 4.9986 8.6492 N.am 1 RES1 0.0000
+ 4 H1 11.0244 4.4851 8.3214 H 1 RES1 0.0000
+ 5 C1 9.1320 4.5536 8.6107 C.2 1 RES1 0.0000
+ 6 C2 8.1269 5.4172 9.2306 C.2 1 RES1 0.0000
+ 7 C3 8.5142 6.6092 9.7308 C.2 1 RES1 0.0000
+ 8 C4 9.8756 7.0655 9.7265 C.ar 1 RES1 0.0000
+ 9 C5 10.3180 8.3141 10.2229 C.ar 1 RES1 0.0000
+ 10 H2 9.7044 8.9080 10.5921 H 1 RES1 0.0000
+ 11 C6 11.6338 8.6516 10.1632 C.ar 1 RES1 0.0000
+ 12 H3 11.9108 9.4781 10.4877 H 1 RES1 0.0000
+ 13 C7 12.5659 7.7809 9.6266 C.ar 1 RES1 0.0000
+ 14 H4 13.4630 8.0220 9.6019 H 1 RES1 0.0000
+ 15 C8 12.1712 6.5589 9.1304 C.ar 1 RES1 0.0000
+ 16 H5 12.7976 5.9734 8.7697 H 1 RES1 0.0000
+ 17 C9 10.8255 6.2081 9.1730 C.ar 1 RES1 0.0000
+ 18 C10 6.7184 4.9288 9.2776 C.ar 1 RES1 0.0000
+ 19 C11 6.3424 4.0058 10.2375 C.ar 1 RES1 0.0000
+ 20 H6 6.9742 3.6788 10.8362 H 1 RES1 0.0000
+ 21 C12 5.0343 3.5663 10.3142 C.ar 1 RES1 0.0000
+ 22 H7 4.7881 2.9542 10.9698 H 1 RES1 0.0000
+ 23 C13 4.0980 4.0323 9.4207 C.ar 1 RES1 0.0000
+ 24 H8 3.2170 3.7361 9.4714 H 1 RES1 0.0000
+ 25 C14 4.4611 4.9274 8.4627 C.ar 1 RES1 0.0000
+ 26 H9 3.8312 5.2341 7.8516 H 1 RES1 0.0000
+ 27 C15 5.7662 5.3822 8.3966 C.ar 1 RES1 0.0000
+ 28 H10 6.0021 6.0041 7.7457 H 1 RES1 0.0000
+@BOND
+ 1 1 7 1
+ 2 2 5 2
+ 3 3 4 1
+ 4 5 3 am
+ 5 6 5 1
+ 6 7 6 2
+ 7 8 7 1
+ 8 9 8 ar
+ 9 10 9 1
+ 10 11 9 ar
+ 11 12 11 1
+ 12 13 11 ar
+ 13 14 13 1
+ 14 15 13 ar
+ 15 16 15 1
+ 16 17 3 1
+ 17 18 6 1
+ 18 19 18 ar
+ 19 20 19 1
+ 20 21 19 ar
+ 21 22 21 1
+ 22 23 21 ar
+ 23 24 23 1
+ 24 25 23 ar
+ 25 26 25 1
+ 26 27 18 ar
+ 27 28 27 1
+ 28 8 17 ar
+ 29 15 17 ar
+ 30 25 27 ar
+@SUBSTRUCTURE
+ 1 RES1 1 GROUP 0 **** **** 0
+@CRYSIN
+ 11.1366 6.9872 15.3869 90.0000 93.7960 90.0000 14 1
diff --git a/scripts/core/simplifier/tests/test_simplifier.py b/scripts/core/simplifier/tests/test_simplifier.py
new file mode 100644
index 0000000..73e1fe4
--- /dev/null
+++ b/scripts/core/simplifier/tests/test_simplifier.py
@@ -0,0 +1,642 @@
+#
+# This script can be used for any purpose without limitation subject to the
+# conditions at http://www.ccdc.cam.ac.uk/Community/Pages/Licences/v2.aspx
+#
+# This permission notice and the following statement of attribution must be
+# included in all copies or substantial portions of this script.
+#
+# 2024-10-30 Created by Alex Moldovan, the Cambridge Crystallographic Data Centre
+# ccdc-licence-features not-applicable
+#
+
+from pathlib import Path
+
+import ccdc.crystal
+import ccdc.io
+import ccdc.molecule
+import ccdc.search
+import json
+import numpy as np
+import os
+import sys
+import tempfile
+import unittest
+import warnings
+from unittest.mock import MagicMock, patch
+
+SIMPLIFIER_DIR = Path(__file__).resolve().parent.parent
+if str(SIMPLIFIER_DIR) not in sys.path:
+ sys.path.insert(0, str(SIMPLIFIER_DIR))
+
+import simplifier as simplifier_mod # noqa: E402
+from simplifier import ( # noqa: E402
+ MercuryInterface,
+ NothingToSmileAbout,
+ Simplifier,
+ SimplifierData,
+ get_args,
+ markdown_to_html,
+ simplifier_cl,
+ swap_two,
+)
+
+warnings.filterwarnings("ignore", category=DeprecationWarning)
+
+ABABEL_MOL2_PATH = Path(__file__).resolve().parent / "ABABEL.mol2"
+
+
+def load_ababel_crystal(identifier: str = None) -> ccdc.crystal.Crystal:
+ """Load the static ABABEL.mol2 crystal fixture."""
+ crystal = ccdc.io.CrystalReader(str(ABABEL_MOL2_PATH))[0]
+ if identifier is not None:
+ crystal.identifier = identifier
+ return crystal
+
+
+def create_multicomponent_ababel_crystal(
+ identifier: str = "ABABEL_HYDRATE",
+) -> ccdc.crystal.Crystal:
+ """Create a multi-component Crystal from ABABEL.mol2 plus a water molecule."""
+ crystal = load_ababel_crystal(identifier=identifier)
+ mol = crystal.molecule
+ water = ccdc.molecule.Molecule.from_string("O", format="smiles")
+ for idx, atom in enumerate(water.atoms):
+ atom.coordinates = (25.0 + float(idx) * 1.0, 25.0, 25.0)
+ atom.label = f"W{atom.atomic_symbol}{idx + 1}"
+ mol.add_molecule(water)
+ crystal.molecule = mol
+ return crystal
+
+
+class TestSwapTwo(unittest.TestCase):
+ """Tests for the swap_two matrix utility function."""
+
+ def test_swap_rows_and_columns(self):
+ arr = np.array(
+ [
+ [0, 1, 5],
+ [1, 0, 2],
+ [5, 2, 0],
+ ]
+ )
+ swapped = swap_two(arr, 0, 2)
+ expected = np.array(
+ [
+ [0, 2, 5],
+ [2, 0, 1],
+ [5, 1, 0],
+ ]
+ )
+ np.testing.assert_array_equal(swapped, expected)
+
+ def test_swap_does_not_mutate_original_array(self):
+ arr = np.arange(9).reshape(3, 3)
+ original_copy = arr.copy()
+ _ = swap_two(arr, 0, 1)
+ np.testing.assert_array_equal(arr, original_copy)
+
+ def test_swap_same_index_is_identity(self):
+ arr = np.arange(16).reshape(4, 4)
+ swapped = swap_two(arr, 2, 2)
+ np.testing.assert_array_equal(swapped, arr)
+
+
+class TestSimplifierData(unittest.TestCase):
+ """Tests for SimplifierData cache management."""
+
+ def setUp(self):
+ self.temp_dir = tempfile.TemporaryDirectory()
+ self.temp_path = Path(self.temp_dir.name)
+
+ def tearDown(self):
+ self.temp_dir.cleanup()
+
+ def test_invalid_parent_directory_raises_not_a_directory(self):
+ invalid_cache = self.temp_path / "non_existent_subdir" / "cache.json"
+ with self.assertRaises(NotADirectoryError):
+ SimplifierData(cache_storage=invalid_cache)
+
+ def test_creates_new_cache_file_when_missing(self):
+ cache_file = self.temp_path / "new_cache.json"
+ self.assertFalse(cache_file.exists())
+
+ data = SimplifierData(cache_storage=str(cache_file))
+ self.assertIsInstance(data.cache_storage, Path)
+ self.assertTrue(cache_file.is_file())
+ self.assertEqual(data.smiles, {})
+ self.assertEqual(data.connectivity, {})
+
+ disk_content = json.loads(cache_file.read_text())
+ self.assertEqual(disk_content, {"smiles": {}, "connectivity": {}})
+
+ def test_loads_existing_cache_file_on_init(self):
+ cache_file = self.temp_path / "existing_cache.json"
+ initial_payload = {
+ "smiles": {"HYQUIN08": "[#8H:0]c1ccc([#8H:1])cc1"},
+ "connectivity": {"HYQUIN08": "01"},
+ }
+ cache_file.write_text(json.dumps(initial_payload))
+
+ data = SimplifierData(cache_storage=cache_file)
+ self.assertEqual(data.smiles, initial_payload["smiles"])
+ self.assertEqual(data.connectivity, initial_payload["connectivity"])
+
+ def test_load_from_file_raises_file_not_found_if_deleted(self):
+ cache_file = self.temp_path / "temp_cache.json"
+ data = SimplifierData(cache_storage=cache_file)
+ cache_file.unlink()
+
+ with self.assertRaises(FileNotFoundError):
+ data.load_from_file()
+
+ def test_update_data_persists_to_disk(self):
+ cache_file = self.temp_path / "update_cache.json"
+ data = SimplifierData(cache_storage=cache_file)
+
+ data.update_data("ACEMID01", "CC([#7H2:1])=[#8:0]", "01")
+ self.assertEqual(data.smiles["ACEMID01"], "CC([#7H2:1])=[#8:0]")
+ self.assertEqual(data.connectivity["ACEMID01"], "01")
+
+ reloaded = SimplifierData(cache_storage=cache_file)
+ self.assertEqual(reloaded.smiles["ACEMID01"], "CC([#7H2:1])=[#8:0]")
+ self.assertEqual(reloaded.connectivity["ACEMID01"], "01")
+
+
+class TestSimplifier(unittest.TestCase):
+ """Tests for the core Simplifier class methods."""
+
+ def setUp(self):
+ self.temp_dir = tempfile.TemporaryDirectory()
+ self.temp_path = Path(self.temp_dir.name)
+ self.cache_file = self.temp_path / "simplifier_data.json"
+ self.simplifier = Simplifier(data_path=self.cache_file)
+
+ def tearDown(self):
+ self.temp_dir.cleanup()
+
+ def test_properties_getters_and_setters(self):
+ self.assertIsNone(self.simplifier.selected_smiles)
+ self.assertIsNone(self.simplifier.connectivity)
+ self.assertIsNone(self.simplifier.selected_molecule)
+
+ mol = ccdc.molecule.Molecule.from_string("CCO", format="smiles")
+ self.simplifier.selected_smiles = "[#6:0][#6:1][#8:2]"
+ self.simplifier.connectivity = "0112"
+ self.simplifier.selected_molecule = mol
+
+ self.assertEqual(self.simplifier.selected_smiles, "[#6:0][#6:1][#8:2]")
+ self.assertEqual(self.simplifier.connectivity, "0112")
+ self.assertEqual(self.simplifier.selected_molecule, mol)
+
+ def test_connectivity_typog(self):
+ self.assertIsNone(self.simplifier.connectivity_typog())
+
+ self.simplifier.connectivity = "01"
+ self.assertEqual(self.simplifier.connectivity_typog(), "0-1")
+
+ self.simplifier.connectivity = "011223"
+ self.assertEqual(self.simplifier.connectivity_typog(), "0-1, 1-2, 2-3")
+
+ def test_optimise_association_matrix_branching_true(self):
+ # 4 atoms: atom 2 is closest to atom 0, atom 3 is closest to atom 1
+ distances = np.array(
+ [
+ [0, 2, 1, 4],
+ [2, 0, 3, 1],
+ [1, 3, 0, 5],
+ [4, 1, 5, 0],
+ ]
+ )
+ atoms = ["A0", "A1", "A2", "A3"]
+ out_atoms, conn = Simplifier.optimise_association_matrix_with_connectivity(
+ distances, atoms, branching=True
+ )
+ self.assertEqual(out_atoms, ["A0", "A1", "A2", "A3"])
+ # row 0 & 1 -> '01'; row 2 min in [:2] is idx 0 -> '02'; row 3 min in [:3] is idx 1 -> '13'
+ self.assertEqual(conn, "010213")
+
+ def test_optimise_association_matrix_branching_false(self):
+ # Linear chain A - B - C where initial order is [A, C, B] (distances: A-C=4, C-B=2, A-B=2)
+ distances = np.array(
+ [
+ [0, 4, 2],
+ [4, 0, 2],
+ [2, 2, 0],
+ ]
+ )
+ atoms = ["A", "C", "B"]
+ out_atoms, conn = Simplifier.optimise_association_matrix_with_connectivity(
+ distances, atoms, iterations=5, branching=False
+ )
+ self.assertEqual(conn, "0112")
+ # Swapping index 1 and 2 reduces super-diagonal sum from (4 + 2 = 6) to (2 + 2 = 4)
+ self.assertEqual(out_atoms, ["A", "B", "C"])
+
+ def test_get_selected_atoms_and_connectivity_counts(self):
+ crystal = load_ababel_crystal()
+ self.simplifier.selected_molecule = crystal.molecule
+
+ # 0 atoms -> ValueError
+ with self.assertRaises(ValueError):
+ self.simplifier.get_selected_atoms_and_connectivity([])
+
+ # 1 atom -> ValueError (must select more than 1 atom)
+ self.simplifier.selected_molecule = load_ababel_crystal().molecule
+ with self.assertRaises(ValueError):
+ self.simplifier.get_selected_atoms_and_connectivity(
+ [self.simplifier.selected_molecule.atoms[0]]
+ )
+
+ # 2 atoms -> '01'
+ self.simplifier.selected_molecule = load_ababel_crystal().molecule
+ atoms_2, conn_2 = self.simplifier.get_selected_atoms_and_connectivity(
+ self.simplifier.selected_molecule.atoms[:2]
+ )
+ self.assertEqual(len(atoms_2), 2)
+ self.assertEqual(conn_2, "01")
+
+ # 3 atoms -> 2 pairs (4 characters)
+ self.simplifier.selected_molecule = load_ababel_crystal().molecule
+ heavy_atoms = [a for a in self.simplifier.selected_molecule.atoms if a.atomic_number > 1]
+ atoms_3, conn_3 = self.simplifier.get_selected_atoms_and_connectivity(
+ heavy_atoms[:3]
+ )
+ self.assertEqual(len(atoms_3), 3)
+ self.assertEqual(len(conn_3), 4)
+
+ def test_alter_molecule_smiles(self):
+ mol = load_ababel_crystal().molecule
+ selected = [mol.atom("Cl1"), mol.atom("O1"), mol.atom("N1")]
+ self.assertEqual(len(selected), 3)
+
+ altered = Simplifier.alter_molecule_smiles(selected, mol)
+ self.assertIn("[#17:0]", altered)
+ self.assertIn("[#8:1]", altered)
+ self.assertIn("[#7H:2]", altered)
+
+ smarts = ccdc.search.SMARTSSubstructure(altered)
+ fresh_mol = load_ababel_crystal().molecule
+ self.assertTrue(smarts.match_molecule(fresh_mol))
+
+ def test_define_simplification_updates_cache(self):
+ crystal = load_ababel_crystal()
+ selected_atoms = [
+ crystal.molecule.atom("Cl1"),
+ crystal.molecule.atom("O1"),
+ crystal.molecule.atom("N1"),
+ ]
+ self.simplifier.define_simplification(crystal, selected_atoms)
+
+ self.assertIn("ABABEL", self.simplifier.simplifier_data.smiles)
+ self.assertIn("ABABEL", self.simplifier.simplifier_data.connectivity)
+ self.assertEqual(
+ self.simplifier.simplifier_data.smiles["ABABEL"],
+ self.simplifier.selected_smiles,
+ )
+
+ def test_get_smarts_success_and_nothing_to_smile_about(self):
+ crystal = load_ababel_crystal()
+
+ # Empty cache raises NothingToSmileAbout
+ with self.assertRaises(NothingToSmileAbout):
+ self.simplifier.get_smarts(crystal)
+
+ # Define simplification on a fresh copy so cache is populated for ABABEL
+ define_crystal = load_ababel_crystal()
+ self.simplifier.define_simplification(
+ define_crystal,
+ [define_crystal.molecule.atom("Cl1"), define_crystal.molecule.atom("O1")],
+ )
+ expected_smiles = self.simplifier.selected_smiles
+
+ smarts = self.simplifier.get_smarts(crystal)
+ self.assertIsInstance(smarts, ccdc.search.SMARTSSubstructure)
+ self.assertEqual(self.simplifier.selected_smiles, expected_smiles)
+ self.assertEqual(self.simplifier.connectivity, "01")
+
+ def test_use_simplification_single_component(self):
+ define_crystal = load_ababel_crystal()
+ self.simplifier.define_simplification(
+ define_crystal,
+ [define_crystal.molecule.atom("Cl1"), define_crystal.molecule.atom("O1")],
+ )
+
+ target_crystal = load_ababel_crystal()
+ self.simplifier.use_simplification(target_crystal)
+ simplified_mol = self.simplifier.selected_molecule
+
+ # Only the 2 mapped atoms (Cl1 and O1) should remain, connected by a single bond
+ self.assertEqual(len(simplified_mol.atoms), 2)
+ self.assertEqual({a.atomic_symbol for a in simplified_mol.atoms}, {"Cl", "O"})
+ self.assertEqual(len(simplified_mol.bonds), 1)
+
+ def test_use_simplification_with_explicit_smarts_and_no_connectivity(self):
+ define_crystal = load_ababel_crystal()
+ self.simplifier.define_simplification(
+ define_crystal,
+ [define_crystal.molecule.atom("Cl1"), define_crystal.molecule.atom("O1")],
+ )
+ ababel_smarts = self.simplifier.selected_smiles
+
+ target_crystal = load_ababel_crystal()
+ fresh_simplifier = Simplifier(data_path=self.cache_file)
+ fresh_simplifier.use_simplification(
+ target_crystal,
+ smarts=ababel_smarts,
+ connectivity="",
+ )
+ simplified_mol = fresh_simplifier.selected_molecule
+ self.assertEqual(len(simplified_mol.atoms), 2)
+ self.assertEqual(len(simplified_mol.bonds), 1)
+
+ def test_use_simplification_leave_vs_remove_unmatched_molecules(self):
+ define_crystal = load_ababel_crystal()
+ self.simplifier.define_simplification(
+ define_crystal,
+ [define_crystal.molecule.atom("Cl1"), define_crystal.molecule.atom("O1")],
+ )
+
+ # Multi-component crystal: ABABEL + water (3 atoms)
+ multi_crystal_keep = create_multicomponent_ababel_crystal()
+ multi_crystal_remove = create_multicomponent_ababel_crystal()
+
+ # Case 1: leave_unmatched_molecules=True (keeps water component = 3 atoms + 2 simplified atoms = 5)
+ simplifier_keep = Simplifier(
+ data_path=self.cache_file, leave_unmatched_molecules=True
+ )
+ simplifier_keep.use_simplification(multi_crystal_keep)
+ self.assertEqual(len(simplifier_keep.selected_molecule.atoms), 5)
+
+ # Case 2: leave_unmatched_molecules=False (removes water component, leaving only 2 simplified atoms)
+ simplifier_remove = Simplifier(
+ data_path=self.cache_file, leave_unmatched_molecules=False
+ )
+ simplifier_remove.use_simplification(multi_crystal_remove)
+ self.assertEqual(len(simplifier_remove.selected_molecule.atoms), 2)
+
+ def test_simplification_diagram_returns_base64_img_tag(self):
+ define_crystal = load_ababel_crystal()
+ self.simplifier.define_simplification(
+ define_crystal,
+ [define_crystal.molecule.atom("Cl1"), define_crystal.molecule.atom("O1")],
+ )
+ html_img = self.simplifier.simplification_diagram()
+ self.assertTrue(
+ html_img.startswith(
+ '
{expected_smiles}
', combined_html)
+ self.assertIn("Connectivity: 0-1", combined_html)
+ self.assertIn("data:image/png;base64,", combined_html)
+
+
+class TestSimplifierCLI(unittest.TestCase):
+ """Tests for command-line parsing (get_args) and execution (simplifier_cl)."""
+
+ def setUp(self):
+ self.temp_dir = tempfile.TemporaryDirectory()
+ self.temp_path = Path(self.temp_dir.name)
+ self.cache_file = self.temp_path / "simplifier_data.json"
+ simplifier = Simplifier(data_path=self.cache_file)
+ define_crystal = load_ababel_crystal()
+ simplifier.define_simplification(
+ define_crystal,
+ [define_crystal.molecule.atom("Cl1"), define_crystal.molecule.atom("O1")],
+ )
+ self.ababel_smarts = simplifier.selected_smiles
+
+ def tearDown(self):
+ self.temp_dir.cleanup()
+
+ def test_get_args_parsing(self):
+ test_argv = [
+ "simplifier.py",
+ "structure1.cif",
+ "structure2.mol2",
+ "-s",
+ self.ababel_smarts,
+ "-c",
+ "01",
+ "-od",
+ str(self.temp_path),
+ "-ff",
+ "cif",
+ "-v",
+ "-rm",
+ "-ma",
+ "-as",
+ "-sd",
+ str(self.cache_file),
+ ]
+ with patch.object(sys, "argv", test_argv):
+ args = get_args()
+
+ self.assertEqual(args.idents, ["structure1.cif", "structure2.mol2"])
+ self.assertEqual(args.smarts, self.ababel_smarts)
+ self.assertEqual(args.connectivity, "01")
+ self.assertEqual(args.output_directory, str(self.temp_path))
+ self.assertEqual(args.file_format, "cif")
+ self.assertTrue(args.verbose)
+ self.assertTrue(args.remove_unmatched)
+ self.assertTrue(args.match_all)
+ self.assertTrue(args.add_smarts)
+ self.assertEqual(args.simplifier_data, str(self.cache_file))
+
+ def test_simplifier_cl_add_smarts(self):
+ test_argv = [
+ "simplifier.py",
+ "NEWREF",
+ "-as",
+ "-s",
+ "[#7H2:0]c1ccc([#8H:1])cc1[#6H:2]",
+ "-sd",
+ str(self.cache_file),
+ ]
+ with patch.object(sys, "argv", test_argv):
+ simplifier_cl()
+
+ data = SimplifierData(cache_storage=self.cache_file)
+ self.assertEqual(data.smiles["NEWREF"], "[#7H2:0]c1ccc([#8H:1])cc1[#6H:2]")
+ self.assertEqual(data.connectivity["NEWREF"], "0112")
+
+ def test_simplifier_cl_local_mol2_file_and_parameters(self):
+ params_path = self.temp_path / "params.json"
+ params_path.write_text(json.dumps({"verbose": True}))
+
+ out_dir = self.temp_path / "outputs"
+ out_dir.mkdir()
+
+ test_argv = [
+ "simplifier.py",
+ str(ABABEL_MOL2_PATH),
+ "-od",
+ str(out_dir),
+ "-p",
+ str(params_path),
+ "-sd",
+ str(self.cache_file),
+ ]
+ with patch.object(sys, "argv", test_argv):
+ simplifier_cl()
+
+ simplified_file = out_dir / "ABABEL_s.mol2"
+ combined_file = out_dir / "combined.mol2"
+ self.assertTrue(simplified_file.is_file())
+ self.assertTrue(combined_file.is_file())
+ self.assertGreater(combined_file.stat().st_size, 0)
+
+ reloaded = ccdc.io.CrystalReader(str(simplified_file))[0]
+ self.assertEqual(len(reloaded.molecule.atoms), 2)
+
+ def test_simplifier_cl_cwd_and_smarts_override(self):
+ work_dir = self.temp_path / "cwd_test"
+ work_dir.mkdir()
+ local_mol2 = work_dir / "sample.mol2"
+ local_mol2.write_text(ABABEL_MOL2_PATH.read_text())
+
+ old_cwd = os.getcwd()
+ try:
+ os.chdir(work_dir)
+ test_argv = [
+ "simplifier.py",
+ "cwd",
+ "-s",
+ self.ababel_smarts,
+ "-sd",
+ str(self.cache_file),
+ ]
+ with patch.object(sys, "argv", test_argv):
+ simplifier_cl()
+
+ self.assertTrue((work_dir / "sample_s.mol2").is_file())
+ self.assertTrue((work_dir / "combined.mol2").is_file())
+ finally:
+ os.chdir(old_cwd)
+
+ def test_simplifier_cl_warns_on_unmatched_structure(self):
+ empty_cache = self.temp_path / "empty_cache.json"
+ SimplifierData(cache_storage=empty_cache)
+
+ out_dir = self.temp_path / "unmatched_out"
+ out_dir.mkdir()
+
+ test_argv = [
+ "simplifier.py",
+ str(ABABEL_MOL2_PATH),
+ "-od",
+ str(out_dir),
+ "-sd",
+ str(empty_cache),
+ ]
+ with patch.object(sys, "argv", test_argv):
+ with warnings.catch_warnings(record=True) as caught:
+ warnings.simplefilter("always")
+ simplifier_cl()
+ warning_messages = [str(w.message) for w in caught]
+ self.assertTrue(
+ any("has no smiles stored in cache" in m for m in warning_messages)
+ )
+
+
+class TestMercuryInterface(unittest.TestCase):
+ """Tests for MercuryInterface with mocked ApplicationInterface."""
+
+ def setUp(self):
+ self.temp_dir = tempfile.TemporaryDirectory()
+ self.temp_path = Path(self.temp_dir.name)
+ # MercuryInterface uses Path(working_directory_path).parents[2] / "simplifier_cache"
+ self.working_dir = self.temp_path / "level1" / "level2" / "work_dir"
+ self.working_dir.mkdir(parents=True)
+
+ def tearDown(self):
+ self.temp_dir.cleanup()
+
+ @patch.object(simplifier_mod, "ApplicationInterface")
+ def test_mercury_interface_init_and_write_readme(self, mock_app_interface_cls):
+ mock_app = MagicMock()
+ mock_app.working_directory_path = str(self.working_dir)
+ mock_app.current_entry.crystal = load_ababel_crystal()
+ output_html = self.working_dir / "output.html"
+ mock_app.output_html_file = str(output_html)
+ mock_app.output_mol2_file = str(self.working_dir / "output.mol2")
+ mock_app.selected_atoms = []
+ mock_app_interface_cls.return_value = mock_app
+
+ mi = MercuryInterface(leave_unmatched_molecules=False)
+ expected_cache_dir = self.temp_path / "simplifier_cache"
+ self.assertTrue(expected_cache_dir.is_dir())
+ self.assertFalse(mi.simplifier.leave_unmatched_molecules)
+
+ # When no atoms are selected, write_readme_if_none_selected renders readme.md to HTML and returns True
+ self.assertTrue(mi.write_readme_if_none_selected())
+ self.assertTrue(output_html.is_file())
+ rendered_html = output_html.read_text(encoding="utf-8")
+ expected_html = markdown_to_html(
+ (SIMPLIFIER_DIR / "readme.md").read_text(encoding="utf-8")
+ )
+ self.assertEqual(rendered_html, expected_html)
+ self.assertIn("1 atoms are selected, write_readme_if_none_selected returns False
+ mock_app.selected_atoms = mock_app.current_entry.crystal.molecule.atoms[:2]
+ self.assertFalse(mi.write_readme_if_none_selected())
+
+ @patch.object(simplifier_mod, "ApplicationInterface")
+ def test_mercury_interface_write_output(self, mock_app_interface_cls):
+ mock_app = MagicMock()
+ mock_app.working_directory_path = str(self.working_dir)
+ mock_app.current_entry.crystal = load_ababel_crystal()
+ mock_app.output_mol2_file = str(self.working_dir / "output.mol2")
+ mock_app_interface_cls.return_value = mock_app
+
+ mi = MercuryInterface(leave_unmatched_molecules=True)
+ mi.simplifier.write_output = MagicMock()
+ mi.simplifier.write_output_molecule = MagicMock()
+
+ mi.write_output()
+ mi.simplifier.write_output.assert_called_once_with(interface=mock_app)
+ mi.simplifier.write_output_molecule.assert_called_once_with(
+ file_output=mock_app.output_mol2_file,
+ crystal=mi.crystal,
+ )
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/scripts/core/simplifier/use_simplifier.py b/scripts/core/simplifier/use_simplifier.py
new file mode 100644
index 0000000..b389435
--- /dev/null
+++ b/scripts/core/simplifier/use_simplifier.py
@@ -0,0 +1,22 @@
+#
+# This script can be used for any purpose without limitation subject to the
+# conditions at http://www.ccdc.cam.ac.uk/Community/Pages/Licences/v2.aspx
+#
+# This permission notice and the following statement of attribution must be
+# included in all copies or substantial portions of this script.
+#
+# 2023-08-18 Created by Chris Kingsbury, the Cambridge Crystallographic Data Centre
+# ORCID 0000-0002-4694-5566
+# flake8: noqa
+#
+import sys
+
+from simplifier import simplifier_cl, MercuryInterface
+
+if __name__ == "__main__":
+ if len(sys.argv) > 3 and sys.argv[3].endswith(".m2a"):
+ mercury_interface = MercuryInterface(leave_unmatched_molecules=True)
+ mercury_interface.simplifier.use_simplification(crystal=mercury_interface.crystal)
+ mercury_interface.write_output()
+ else:
+ simplifier_cl()
diff --git a/scripts/core/simplifier/use_simplifier_remove_unmatched.py b/scripts/core/simplifier/use_simplifier_remove_unmatched.py
new file mode 100644
index 0000000..5a22843
--- /dev/null
+++ b/scripts/core/simplifier/use_simplifier_remove_unmatched.py
@@ -0,0 +1,21 @@
+#
+# This script can be used for any purpose without limitation subject to the
+# conditions at http://www.ccdc.cam.ac.uk/Community/Pages/Licences/v2.aspx
+#
+# This permission notice and the following statement of attribution must be
+# included in all copies or substantial portions of this script.
+#
+# 2023-08-18 Created by Chris Kingsbury, the Cambridge Crystallographic Data Centre
+# ORCID 0000-0002-4694-5566
+# flake8: noqa
+import sys
+
+from simplifier import MercuryInterface
+
+if __name__ == "__main__":
+ if len(sys.argv) > 3 and sys.argv[3].endswith(".m2a"):
+ mercury_interface = MercuryInterface(leave_unmatched_molecules=False)
+ mercury_interface.simplifier.use_simplification(crystal=mercury_interface.crystal)
+ mercury_interface.write_output()
+ else:
+ raise NotImplementedError("Implementation is for Mercury - CSD Python API menu only")