molify 0.2.5__tar.gz → 0.2.7__tar.gz

{molify-0.2.5 → molify-0.2.7}/.github/workflows/pytest.yaml

@@ -21,8 +21,8 @@ jobs:
           - "3.12"
           - "3.11"
           - "3.10"
-        os: [ubuntu-latest, ubuntu-24.04-arm, windows-latest, macos-15-intel, macos-latest]
-        # windows-11-arm -> rdkit support missing
+        os: [ubuntu-latest, ubuntu-24.04-arm, windows-latest, macos-latest]
+        # windows-11-arm, macos-15-intel -> rdkit support missing
 
     steps:
       - uses: actions/checkout@v5

{molify-0.2.5 → molify-0.2.7}/.pre-commit-config.yaml

@@ -20,13 +20,13 @@ repos:
       - id: sort-simple-yaml
       - id: trailing-whitespace
   - repo: https://github.com/codespell-project/codespell
-    rev: v2.4.1
+    rev: v2.4.3
     hooks:
       - id: codespell
         additional_dependencies: ["tomli"]
   - repo: https://github.com/astral-sh/ruff-pre-commit
     # Ruff version.
-    rev: v0.14.14
+    rev: v0.16.10
     hooks:
       # Run the linter.
       - id: ruff

{molify-0.2.5 → molify-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: molify
-Version: 0.2.5
+Version: 0.2.7
 Summary: Molecular Structure Interface with RDKit, ASE, Packmol and NetworkX
 Project-URL: Repository, https://github.com/zincware/molify
 Project-URL: Releases, https://github.com/zincware/molify/releases
@@ -15,6 +15,8 @@ Requires-Dist: matplotlib>=3.10.1
 Requires-Dist: networkx>=3.4.2
 Requires-Dist: packmol>=21.1.2
 Requires-Dist: rdkit>=2024
+Requires-Dist: typer>=0.27.1
+Requires-Dist: typing-extensions>=4.15.0
 Provides-Extra: vesin
 Requires-Dist: vesin>=0.3.7; extra == 'vesin'
 Description-Content-Type: text/markdown
@@ -58,6 +60,15 @@ print(atoms)
 >>> Atoms(symbols='OH2', pbc=False)
 ```
 
+## Command Line Interface
+
+Commands mirror the molify functions and write to standard output. `--format`
+takes any ASE format name or extension, defaulting to extxyz.
+
+```bash
+molify smiles2atoms CCO > etoh.xyz
+```
+
 ## Packmol Interface
 
 Given the molecular units, you can build periodic boxes with a given density

{molify-0.2.5 → molify-0.2.7}/README.md

@@ -37,6 +37,15 @@ print(atoms)
 >>> Atoms(symbols='OH2', pbc=False)
 ```
 
+## Command Line Interface
+
+Commands mirror the molify functions and write to standard output. `--format`
+takes any ASE format name or extension, defaulting to extxyz.
+
+```bash
+molify smiles2atoms CCO > etoh.xyz
+```
+
 ## Packmol Interface
 
 Given the molecular units, you can build periodic boxes with a given density

{molify-0.2.5 → molify-0.2.7}/docs/source/index.rst

@@ -100,6 +100,15 @@ The networkx.Graph representation can be obtained from either RDKit or ASE objec
    nh3_graph = molify.ase2networkx(nh3_atoms)
 
 
+**Command Line Interface**
+
+Commands mirror the molify functions and write to standard output. ``--format``
+takes any ASE format name or extension, defaulting to extxyz.
+
+.. code-block:: console
+
+   $ molify smiles2atoms CCO > etoh.xyz
+
 Advanced Features
 -----------------
 

{molify-0.2.5 → molify-0.2.7}/docs/source/packmol_tools.ipynb

@@ -284,6 +284,45 @@
     "print(f\"Density: {actual_density:.1f} kg/m³\")"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Repeating a Box\n",
+    "\n",
+    "`molify.repeat()` builds a supercell of a periodic box and tiles `info['connectivity']` with it. Every copy carries its own bonds, bonds across the periodic boundary link neighbouring copies, and bond orders are kept. Use it to repeat any structure that carries connectivity."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 9,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Atoms: 60 -> 120\n",
+      "Bonds: 50 -> 100\n",
+      "Molecules: 10 -> 20\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Tile the mixture twice along the first cell vector\n",
+    "supercell = molify.repeat(mixture, (2, 1, 1))\n",
+    "\n",
+    "print(f\"Atoms: {len(mixture)} -> {len(supercell)}\")\n",
+    "print(\n",
+    "    f\"Bonds: {len(mixture.info['connectivity'])} \"\n",
+    "    f\"-> {len(supercell.info['connectivity'])}\"\n",
+    ")\n",
+    "print(\n",
+    "    f\"Molecules: {len(list(molify.iter_fragments(mixture)))} \"\n",
+    "    f\"-> {len(list(molify.iter_fragments(supercell)))}\"\n",
+    ")"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

{molify-0.2.5 → molify-0.2.7}/paper/paper.md

@@ -110,10 +110,7 @@ For example, `molify` streamlines the extraction of the CH$_3$ alkyl group from
 ```python
 from molify import get_substructures
 
-frames: list[ase.Atoms] = get_substructures(
-  atoms=box,
-  smiles="[C]([H])([H])[H]"
-)
+frames: list[ase.Atoms] = get_substructures(atoms=box, smiles="[C]([H])([H])[H]")
 ```
 
 # Related software

{molify-0.2.5 → molify-0.2.7}/pyproject.toml

@@ -14,6 +14,8 @@ dependencies = [
     "networkx>=3.4.2",
     "packmol>=21.1.2",
     "rdkit>=2024",
+    "typer>=0.27.1",
+    "typing-extensions>=4.15.0",
 ]
 
 [dependency-groups]
@@ -32,6 +34,9 @@ docs = [
     "sphinxcontrib-mermaid>=1.0.0",
 ]
 
+[project.scripts]
+molify = "molify.cli:app"
+
 [project.optional-dependencies]
 
 vesin = [

{molify-0.2.5 → molify-0.2.7}/src/molify/__init__.py

@@ -6,6 +6,7 @@ from molify.compress import compress
 from molify.networkx2x import networkx2ase, networkx2rdkit
 from molify.pack import pack
 from molify.rdkit2x import rdkit2ase, rdkit2networkx
+from molify.repeat import repeat
 from molify.smiles2x import smiles2atoms, smiles2conformers
 from molify.substructure import (
     get_substructures,
@@ -27,6 +28,7 @@ __all__ = [
     "pack",
     "smiles2conformers",
     "compress",
+    "repeat",
     "match_substructure",
     "group_matches_by_fragment",
     "get_substructures",

molify-0.2.7/src/molify/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for ``python -m molify``."""
+
+from molify.cli import app
+
+if __name__ == "__main__":
+    app()

{molify-0.2.5 → molify-0.2.7}/src/molify/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.5'
-__version_tuple__ = version_tuple = (0, 2, 5)
+__version__ = version = '0.2.7'
+__version_tuple__ = version_tuple = (0, 2, 7)
 
 __commit_id__ = commit_id = None

{molify-0.2.5 → molify-0.2.7}/src/molify/ase2x.py

@@ -1,16 +1,21 @@
 import ase
 import networkx as nx
 import numpy as np
-from ase.neighborlist import natural_cutoffs, neighbor_list
+from ase.data import covalent_radii
+from ase.neighborlist import neighbor_list
 from rdkit import Chem
 
 from molify.constants import EdgeAttr, GraphAttr, NodeAttr
+from molify.utils import read_connectivity
 
 try:
     import vesin
 except ImportError:
     vesin = None
 
+# Li, Na, K, Rb, Cs, Fr
+_NON_BONDING_ATOMIC_NUMBERS = (3, 11, 19, 37, 55, 87)
+
 
 def _create_graph_from_connectivity(
     atoms: ase.Atoms, connectivity, charges
@@ -39,17 +44,30 @@ def _create_graph_from_connectivity(
     return graph
 
 
-def _compute_connectivity_matrix(atoms: ase.Atoms, scale: float, pbc: bool):
-    """Compute connectivity matrix from distance-based cutoffs."""
-    # non-bonding positive charged atoms / ions.
-    non_bonding_atomic_numbers = {3, 11, 19, 37, 55, 87}
+def _compute_bonded_pairs(atoms: ase.Atoms, scale: float, pbc: bool) -> np.ndarray:
+    """Compute bonded atom pairs from distance-based cutoffs.
 
-    atomic_numbers = atoms.get_atomic_numbers()
-    excluded_mask = np.isin(atomic_numbers, list(non_bonding_atomic_numbers))
+    Parameters
+    ----------
+    atoms : ase.Atoms
+        Structure to search for bonds.
+    scale : float
+        Factor applied to the covalent radii.
+    pbc : bool
+        Whether bonds may cross periodic boundaries.
 
-    atom_radii = np.array(natural_cutoffs(atoms, mult=scale))
-    pairwise_cutoffs = atom_radii[:, None] + atom_radii[None, :]
-    max_cutoff = np.max(pairwise_cutoffs)
+    Returns
+    -------
+    numpy.ndarray
+        Shape ``(M, 2)``; unique ``(i, j)`` rows with ``i < j``, sorted
+        lexicographically.
+    """
+    radii = covalent_radii[atoms.numbers] * scale
+    bonding = ~np.isin(atoms.numbers, _NON_BONDING_ATOMIC_NUMBERS)
+    if not bonding.any():
+        return np.empty((0, 2), dtype=np.intp)
+    # Neighbor lists keep d < cutoff; one ulp more keeps pairs at exactly the cutoff.
+    max_cutoff = np.nextafter(2 * radii[bonding].max(), np.inf)
 
     if vesin is not None:
         try:
@@ -66,31 +84,13 @@ def _compute_connectivity_matrix(atoms: ase.Atoms, scale: float, pbc: bool):
             "ijdS", atoms, cutoff=max_cutoff, self_interaction=False
         )
 
-    # If pbc=False, filter out bonds that cross periodic boundaries
+    keep = (i < j) & bonding[i] & bonding[j] & (d <= radii[i] + radii[j])
     if not pbc:
-        non_periodic_mask = np.all(s == 0, axis=1)
-        i = i[non_periodic_mask]
-        j = j[non_periodic_mask]
-        d = d[non_periodic_mask]
+        keep &= ~s.any(axis=1)
+    return np.unique(np.stack([i[keep], j[keep]], axis=1), axis=0)
 
-    d_ij = np.full((len(atoms), len(atoms)), np.inf)
-    d_ij[i, j] = d
-    np.fill_diagonal(d_ij, 0.0)
 
-    # mask out non-bonding atoms
-    d_ij[excluded_mask, :] = np.inf
-    d_ij[:, excluded_mask] = np.inf
-
-    connectivity_matrix = np.zeros((len(atoms), len(atoms)), dtype=int)
-    np.fill_diagonal(d_ij, np.inf)
-    connectivity_matrix[d_ij <= pairwise_cutoffs] = 1
-
-    return connectivity_matrix, non_bonding_atomic_numbers
-
-
-def _add_node_properties(
-    graph: nx.Graph, atoms: ase.Atoms, charges, non_bonding_atomic_numbers
-):
+def _add_node_properties(graph: nx.Graph, atoms: ase.Atoms, charges):
     """Add node properties to the graph."""
     stored_indices = atoms.info.get(NodeAttr.ORIGINAL_INDEX)
 
@@ -100,7 +100,7 @@ def _add_node_properties(
         graph.nodes[i][NodeAttr.ATOMIC_NUMBER] = int(atom.number)
         graph.nodes[i][NodeAttr.ORIGINAL_INDEX] = original_index
         graph.nodes[i][NodeAttr.CHARGE] = float(charges[i])
-        if atom.number in non_bonding_atomic_numbers:
+        if atom.number in _NON_BONDING_ATOMIC_NUMBERS:
             graph.nodes[i][NodeAttr.CHARGE] = 1.0
 
 
@@ -132,6 +132,12 @@ def ase2networkx(
     networkx.Graph
         An undirected NetworkX graph with connectivity information.
 
+    Raises
+    ------
+    ValueError
+        For an invalid bond in ``atoms.info['connectivity']``, see
+        :func:`molify.utils.read_connectivity`.
+
     Notes
     -----
     The graph contains the following information:
@@ -150,7 +156,11 @@ def ase2networkx(
     Connectivity is determined by:
 
     1. Using explicit connectivity if present in atoms.info
-    2. Otherwise using distance-based cutoffs (edges will have bond_order=None)
+    2. Otherwise using distance-based cutoffs: atoms *i* and *j* are bonded
+       when any periodic image of *j* lies within ``scale * (r_i + r_j)`` of
+       *i*, with *r* the covalent radius. Li, Na, K, Rb, Cs and Fr are
+       non-bonding ions. Edges have ``bond_order=None``; memory scales
+       linearly with the number of atoms.
 
     To get bond orders, pass the graph to networkx2rdkit().
 
@@ -169,24 +179,16 @@ def ase2networkx(
     charges = atoms.get_initial_charges()
 
     if GraphAttr.CONNECTIVITY in atoms.info:
-        connectivity = atoms.info[GraphAttr.CONNECTIVITY]
-        # ensure connectivity is list[tuple[int, int, float|None]] and
-        # does not contain np.generic
-        connectivity = [
-            (int(i), int(j), float(bond_order) if bond_order is not None else None)
-            for i, j, bond_order in connectivity
-        ]
+        connectivity = read_connectivity(atoms)
         return _create_graph_from_connectivity(atoms, connectivity, charges)
 
-    connectivity_matrix, non_bonding_atomic_numbers = _compute_connectivity_matrix(
-        atoms, scale, pbc
-    )
+    pairs = _compute_bonded_pairs(atoms, scale, pbc)
 
-    graph = nx.from_numpy_array(connectivity_matrix, edge_attr=None)
-    for u, v in graph.edges():
-        graph.edges[u, v][EdgeAttr.BOND_ORDER] = None
+    graph = nx.Graph()
+    graph.add_nodes_from(range(len(atoms)))
+    graph.add_edges_from(pairs.tolist(), **{EdgeAttr.BOND_ORDER: None})
 
-    _add_node_properties(graph, atoms, charges, non_bonding_atomic_numbers)
+    _add_node_properties(graph, atoms, charges)
 
     graph.graph[GraphAttr.PBC] = atoms.pbc
     graph.graph[GraphAttr.CELL] = atoms.cell

molify-0.2.7/src/molify/cli.py

@@ -0,0 +1,100 @@
+"""Command line interface for molify."""
+
+import io
+import sys
+from typing import Annotated
+
+import ase.io
+import typer
+from ase.io.formats import extension2format
+
+from molify import __version__
+from molify import smiles2atoms as _smiles2atoms
+
+app = typer.Typer(
+    no_args_is_help=True,
+    add_completion=False,
+    pretty_exceptions_show_locals=False,
+)
+
+
+def _resolve_format(value: str) -> str:
+    """Map a format name or file extension onto an ASE format name.
+
+    Extensions resolve first, so ``XYZ`` selects ASE's ``extxyz`` writer, which
+    keeps the cell and the ``atoms.info`` payload such as the SMILES string and
+    the connectivity.
+
+    Parameters
+    ----------
+    value : str
+        Format name or file extension, in any capitalisation.
+
+    Returns
+    -------
+    str
+        The format name passed on to :func:`ase.io.write`.
+    """
+    key = value.strip().lower()
+    fmt = extension2format.get(key)
+    return fmt.name if fmt is not None else key
+
+
+def _version(value: bool) -> None:
+    """Print the molify version and exit."""
+    if value:
+        typer.echo(__version__)
+        raise typer.Exit
+
+
+@app.callback()
+def main(
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            callback=_version,
+            is_eager=True,
+            help="Show the molify version and exit.",
+        ),
+    ] = False,
+) -> None:
+    """Build molecular structures from the command line.
+
+    Each command mirrors the molify function of the same name and writes the
+    structure to standard output.
+    """
+
+
+@app.command()
+def smiles2atoms(
+    smiles: Annotated[
+        str, typer.Argument(help="SMILES string of the molecule, such as 'CCO'.")
+    ],
+    fmt: Annotated[
+        str,
+        typer.Option(
+            "--format",
+            "-f",
+            help=(
+                "Output format, given as an ASE format name or file extension."
+                " 'XYZ' selects extxyz, which keeps the SMILES string and the"
+                " connectivity."
+            ),
+        ),
+    ] = "extxyz",
+    seed: Annotated[
+        int, typer.Option(help="Random seed for conformer generation.")
+    ] = 42,
+) -> None:
+    """Convert a SMILES string into a single 3D structure on standard output.
+
+    Example: molify smiles2atoms CCO --format XYZ > etoh.xyz
+    """
+    try:
+        atoms = _smiles2atoms(smiles, seed=seed)
+    except ValueError as err:
+        raise typer.BadParameter(str(err), param_hint=["smiles"]) from err
+    with io.StringIO() as handle:
+        ase.io.write(handle, atoms, format=_resolve_format(fmt))
+        sys.stdout.write(handle.getvalue())

molify-0.2.7/src/molify/compress.py

@@ -0,0 +1,52 @@
+import ase
+import numpy as np
+from ase.cell import Cell
+
+from molify.constants import GraphAttr
+from molify.utils import calculate_box_dimensions, fragment_indices
+
+
+def compress(
+    atoms: ase.Atoms,
+    density: float,
+    freeze_molecules: bool = False,
+) -> ase.Atoms:
+    """Compress an ASE Atoms object to a target density.
+
+    Parameters
+    ----------
+    atoms : ase.Atoms
+        The Atoms object to compress.
+    density : float
+        The target density in kg/m^3.
+    freeze_molecules : bool
+        If True, freeze the internal degrees of freedom of the molecules
+        during compression, to prevent bond compression.
+
+    Raises
+    ------
+    ValueError
+        With ``freeze_molecules=True``, for a missing ``info['connectivity']``
+        or an invalid bond in it, see :func:`molify.utils.read_connectivity`.
+    """
+    atoms = atoms.copy()
+    new_dimensions = np.array(calculate_box_dimensions([atoms], density))
+
+    if freeze_molecules:
+        if atoms.info.get(GraphAttr.CONNECTIVITY) is None:
+            raise ValueError("No connectivity info found for freeze_molecules=True")
+        fragments = fragment_indices(atoms)
+        new_cell = Cell.new(new_dimensions)
+        t_mat = np.linalg.solve(atoms.get_cell().T, new_cell.T)
+
+        positions = atoms.get_positions()
+        for fragment in fragments:
+            com = atoms[fragment].get_center_of_mass()
+            positions[fragment] += com @ t_mat - com
+
+        atoms.set_positions(positions)
+        atoms.set_cell(new_cell, scale_atoms=False)
+    else:
+        atoms.set_cell(new_dimensions, scale_atoms=True)
+
+    return atoms

{molify-0.2.5 → molify-0.2.7}/src/molify/pack.py

@@ -10,7 +10,7 @@ from ase.io.proteindatabank import write_proteindatabank
 from rdkit import Chem
 
 from molify.constants import GraphAttr
-from molify.utils import calculate_box_dimensions
+from molify.utils import calculate_box_dimensions, read_connectivity
 
 log = logging.getLogger(__name__)
 
@@ -90,13 +90,29 @@ def _write_molecule_files(
             ase.io.write(filepath, atoms)
 
 
+def _combine_bonds(
+    selected_images: list[ase.Atoms],
+) -> list[tuple[int, int, float | None]] | None:
+    """Offset each molecule's bonds into the packed box.
+
+    Returns None when a molecule lacks ``info['connectivity']``.
+    """
+    if not all(GraphAttr.CONNECTIVITY in atoms.info for atoms in selected_images):
+        return None
+    bonds = []
+    offset = 0
+    for atoms in selected_images:
+        for i, j, order in read_connectivity(atoms):
+            bonds.append((i + offset, j + offset, order))
+        offset += len(atoms)
+    return bonds
+
+
 def _extract_atom_arrays(
     selected_images: list[ase.Atoms], packed_atoms: ase.Atoms
 ) -> ase.Atoms:
     """Extracts and adds relevant atom arrays (if present)
 
-    Add bonds from the input structures to the packed structure if available.
-
     Parameters
     ----------
     selected_images : list[ase.Atoms]
@@ -107,7 +123,7 @@ def _extract_atom_arrays(
     Returns
     -------
     ase.Atoms
-        The packed ASE Atoms object with the copied arrays and bonds.
+        The packed ASE Atoms object with the copied arrays.
     """
     array_keys = [
         "occupancy",
@@ -126,14 +142,6 @@ def _extract_atom_arrays(
             )
             packed_atoms.arrays[key] = concatenated_array
 
-    if all(GraphAttr.CONNECTIVITY in atoms.info for atoms in selected_images):
-        bonds = []
-        offset = 0
-        for atoms in selected_images:
-            for bond in atoms.info[GraphAttr.CONNECTIVITY]:
-                bonds.append((bond[0] + offset, bond[1] + offset, bond[2]))
-            offset += len(atoms)
-        packed_atoms.info[GraphAttr.CONNECTIVITY] = bonds
     charges = np.concatenate([atom.get_initial_charges() for atom in selected_images])
     if any(charge != 0 for charge in charges):
         packed_atoms.set_initial_charges(charges)
@@ -189,6 +197,12 @@ def pack(
     ase.Atoms
         An ASE Atoms object representing the packed system.
 
+    Raises
+    ------
+    ValueError
+        For an invalid bond in a molecule's ``info['connectivity']``, see
+        :func:`molify.utils.read_connectivity`.
+
     Example
     -------
     >>> from molify import pack, smiles2conformers
@@ -200,6 +214,7 @@ def pack(
     Atoms(symbols='C10H44O12', pbc=True, cell=[8.4, 8.4, 8.4])
     """
     selected_images = _select_conformers(data, counts, seed)
+    bonds = _combine_bonds(selected_images)
     cell = calculate_box_dimensions(images=selected_images, density=density)
 
     # Adjust cell dimensions according to ratio while keeping volume unchanged
@@ -240,4 +255,6 @@ def pack(
     packed_atoms.cell = cell
     packed_atoms.pbc = True
     packed_atoms = _extract_atom_arrays(selected_images, packed_atoms)
+    if bonds is not None:
+        packed_atoms.info[GraphAttr.CONNECTIVITY] = bonds
     return packed_atoms