matid 2.2.0__tar.gz → 2.3.0__tar.gz

matid-2.3.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: matid
+Version: 2.3.0
+Summary: MatID is a Python package for identifying and analyzing atomistic systems based on their structure.
+Author: Lauri Himanen
+License-Expression: Apache-2.0
+Project-URL: Documentation, https://fairmat-nfdi.github.io/matid/
+Project-URL: Source, https://github.com/fairmat-nfdi/matid
+Keywords: atoms,structure,materials,science,crystal,symmetry
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: ase
+Requires-Dist: spglib>=2.0.0
+Requires-Dist: networkx>=2.4
+Provides-Extra: dev
+Requires-Dist: coverage; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pydoc-markdown; extra == "dev"
+Requires-Dist: genbadge[coverage]; extra == "dev"
+Dynamic: license-file
+
+<img src="https://raw.githubusercontent.com/fairmat-nfdi/matid/main/docs/static/img/logo.png" width="300">
+
+![Build status](https://github.com/fairmat-nfdi/matid/actions/workflows/test.yml/badge.svg)
+![Coverage Status](./reports/coverage/coverage-badge.svg)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+MatID is a Python package for identifying and analyzing atomistic systems based
+on their structure.
+
+# Documentation
+For more details and tutorials, visit the documentation at:
+[https://fairmat-nfdi.github.io/matid/](https://fairmat-nfdi.github.io/matid/)
+
+You can find even more details in the following open-access articles:
+
+- [Automated identification of bulk structures, two-dimensional materials, and interfaces using symmetry-based clustering](<https://doi.org/10.1038/s41524-024-01498-x>)
+- [Materials structure genealogy and high-throughput topological classification of surfaces and 2D materials](<https://doi.org/10.1038/s41524-018-0107-6>)
+
+## Example: Surface detection and analysis
+
+```python
+import ase.io
+from ase.visualize import view
+
+from matid.clustering import SBC
+from matid.symmetry import SymmetryAnalyzer
+
+# Load structure from a file
+system = ase.io.read('data/system.xyz')
+
+# Find interesting substructures using Symmetry-based Clustering (SBC)
+sbc = SBC()
+clusters = sbc.get_clusters(system)
+
+# Analyze each found cluster printing out the indices of the atoms belonging to
+# this cluster and visualizing the conventional cell from which the cluster was
+# built from.
+for cluster in clusters:
+
+    # Get the indices of the atoms belonging to this cluster
+    indices = cluster.indices
+    print(indices)
+
+    # Get the dimensionality of the cluster
+    dimensionality = cluster.get_dimensionality()
+    print(dimensionality)
+
+    # Get the cell from which the cluster is constructed from. The periodicity
+    # of this cell indicates in which directions the unit cell has been found to
+    # be repeated in (at least once, possibly infinitely).
+    cell = cluster.get_cell()
+    n_repeated_directions = sum(cell.get_pbc())
+    print(n_repeated_directions)
+
+    # Analyze some symmetry properties of the underlying cell to better identify
+    # the material from which the cluster has been constructed from.
+    analyzer = SymmetryAnalyzer(cell, symmetry_tol=0.5)
+    conv_sys = analyzer.get_conventional_system()
+    view(conv_sys)
+```
+
+# Installation
+
+## pip
+```sh
+pip install matid
+```
+
+## From source
+```sh
+git clone https://github.com/fairmat-nfdi/matid.git
+cd matid
+pip install .
+```
+

{matid-2.2.0 → matid-2.3.0}/matid/clustering/sbc.py

@@ -5,7 +5,7 @@ import ase.geometry
 
 import matid.geometry
 from matid.clustering.cluster import Cluster
-from matid.core.periodicfinder import PeriodicFinder
+from matid.core.periodicfinder import PeriodicFinder, get_region_cell_list
 
 
 class SBC:
@@ -115,16 +115,25 @@ class SBC:
 
         # Calculate the distances here once if they have not been provided. A
         # finite radial cutoff is used: the clustering only ever consults local
-        # distances (spans within max_cell_size, and the smaller merge_radius /
-        # bond_threshold thresholds). Pairs beyond the cutoff are reported as
-        # infinite, which fail those same thresholds, so the result is identical
-        # to using an infinite cutoff while being dramatically faster.
+        # distances. Pairs beyond the cutoff are reported as infinite, which
+        # fail the same thresholds, so the result is identical to using an
+        # infinite cutoff while being dramatically faster. The distances are
+        # consulted with the following thresholds:
+        # - Cell spans: raw distance < max_cell_size
+        # - Cluster localization: distance - radii < merge_radius
+        # - Cluster cleaning and dimensionality: distance - radii <= bond_threshold
+        # The cutoff is the smallest one that covers all of these, as the number
+        # of stored neighbours grows with the cube of the cutoff. A small margin
+        # protects against floating point differences at the boundary.
         max_radii = radii.max()
-        cutoff = max(max_cell_size, merge_radius, bond_threshold) + 2 * max_radii
+        cutoff = (
+            max(max_cell_size, max(merge_radius, bond_threshold) + 2 * max_radii) + 1e-6
+        )
         distances = matid.geometry.get_distances(system_copy, radii, cutoff=cutoff)
 
         # Iteratively search for new clusters until whole system is covered
         periodic_finder = PeriodicFinder(angle_tol=angle_tol)
+        cell_list = get_region_cell_list(system_copy, pos_tol)
         indices = set(list(range(len(system_copy))))
         clusters = []
         while len(indices) != 0:
@@ -138,6 +147,7 @@ class SBC:
                 overlap_threshold=overlap_threshold,
                 distances=distances,
                 return_mask=True,
+                cell_list=cell_list,
             )
 
             # All neighbours that the periodic finder has tested are removed
@@ -286,15 +296,15 @@ class SBC:
         """
         # Get all overlapping atoms, and the regions with which they overlap
         overlap_map = defaultdict(list)
-        for i in range(len(system)):
-            for cluster in clusters:
-                if i in cluster.indices:
-                    overlap_map[i].append(cluster)
+        for cluster in clusters:
+            for i in set(cluster.indices):
+                overlap_map[int(i)].append(cluster)
 
         # Assign each overlapping atom to the cluster that is "nearest". Notice
-        # that we do not update the regions during the process.
-        # positions = system.get_positions()
-        for i, i_clusters in overlap_map.items():
+        # that we do not update the regions during the process. The atoms are
+        # processed in ascending index order.
+        for i in sorted(overlap_map):
+            i_clusters = overlap_map[i]
             if len(i_clusters) > 1:
                 surrounding_indices = set(
                     np.where(distances.get_radii_distance_row(i) < merge_radius)[0]
@@ -332,11 +342,22 @@ class SBC:
         for cluster in clusters:
             # If the cluster cleaning fails, the cluster is not reported
             try:
-                dbscan_clusters = matid.geometry.get_clusters(
-                    cluster._get_distance_matrix_radii_mic(),
-                    bond_threshold,
-                    min_samples=1,
-                )
+                # The connectivity is resolved from the sparse neighbour list
+                # instead of a dense distance submatrix, whose size would
+                # scale quadratically with the cluster size.
+                if bond_threshold > 0:
+                    rows, cols = cluster._distances.get_radii_distance_edges(
+                        cluster.indices, bond_threshold
+                    )
+                    dbscan_clusters = matid.geometry.get_clusters_from_edges(
+                        len(cluster.indices), rows, cols
+                    )
+                else:
+                    dbscan_clusters = matid.geometry.get_clusters(
+                        cluster._get_distance_matrix_radii_mic(),
+                        bond_threshold,
+                        min_samples=1,
+                    )
             except Exception:
                 continue
             largest_indices = max(dbscan_clusters, key=len)

{matid-2.2.0 → matid-2.3.0}/matid/core/distances.py

@@ -68,6 +68,32 @@ class Distances:
         self._row_ptr = np.searchsorted(sorted_row, np.arange(n + 1))
         return self
 
+    @classmethod
+    def from_csr(cls, n, row_ptr, col, distance, displacement, factor, radii):
+        """Construct a sparse-backed Distances from a CSR neighbour list, where
+        the neighbours of atom ``i`` are stored in the slice
+        ``row_ptr[i]:row_ptr[i + 1]``. The arrays are used as is, without
+        copying.
+
+        Args:
+            n: Number of atoms.
+            row_ptr: Row offsets, shape (n + 1,).
+            col, distance, displacement, factor: Neighbour data in the same
+                format as for :meth:`from_sparse`, grouped by row.
+            radii: Per-atom radii, shape (n,).
+        """
+        self = cls.__new__(cls)
+        self._dense = False
+        self._n = n
+        self._radii = np.asarray(radii)
+        self.cell_list = None
+        self._row_ptr = np.asarray(row_ptr)
+        self._col = np.asarray(col)
+        self._dist = np.asarray(distance)
+        self._disp = np.asarray(displacement)
+        self._fac = np.asarray(factor)
+        return self
+
     # ------------------------------------------------------------------
     # Dense matrix properties (only valid in dense / infinite-cutoff mode).
     # ------------------------------------------------------------------
@@ -166,3 +192,47 @@ class Distances:
         di = np.arange(k)
         out[di, di] = -2.0 * self._radii[indices]
         return out
+
+    def get_radii_distance_edges(self, indices, threshold):
+        """Returns the local index pairs ``(li, lj)`` with ``li <= lj`` for which
+        ``dist_matrix_radii_mic[np.ix_(indices, indices)] <= threshold``,
+        including the diagonal. The pairs are returned in row-major order.
+
+        This is a sparse alternative to :meth:`get_radii_distance_submatrix`
+        for finding connectivity within a large group of atoms: the memory
+        footprint scales with the number of connected pairs instead of the
+        square of the number of atoms.
+
+        Returns:
+            Two integer arrays ``(li, lj)``.
+        """
+        indices = np.asarray(indices, dtype=np.intp)
+        k = len(indices)
+        if self._dense:
+            submatrix = self._dist_matrix_radii_mic[np.ix_(indices, indices)]
+            li, lj = np.nonzero(np.triu(submatrix <= threshold))
+            return li, lj
+
+        # Gather the neighbour list entries of all requested rows at once.
+        g2l = np.full(self._n, -1, dtype=np.intp)
+        g2l[indices] = np.arange(k)
+        starts = self._row_ptr[indices]
+        lengths = self._row_ptr[indices + 1] - starts
+        li = np.repeat(np.arange(k), lengths)
+        offsets = np.cumsum(lengths) - lengths
+        entries = np.arange(lengths.sum()) + np.repeat(starts - offsets, lengths)
+        cols = self._col[entries]
+        lj = g2l[cols]
+        sel = lj > li
+        li, lj, gi, cols = li[sel], lj[sel], indices[li[sel]], cols[sel]
+        dist = self._dist[entries[sel]] - (self._radii[gi] + self._radii[cols])
+        sel = dist <= threshold
+        li, lj = li[sel], lj[sel]
+
+        # Add the diagonal and order the pairs row-major.
+        diag = np.arange(k)
+        diag = diag[-2.0 * self._radii[indices] <= threshold]
+        li = np.concatenate((li, diag))
+        lj = np.concatenate((lj, diag))
+        order = np.lexsort((lj, li))
+        return li[order], lj[order]

{matid-2.2.0 → matid-2.3.0}/matid/core/linkedunits.py

@@ -32,13 +32,40 @@ class LinkedUnitCollection(dict):
         self.system = system
         self.cell = cell
         self.is_2d = is_2d
-        self._search_graph = nx.MultiDiGraph()
+        self._search_graph_cache = nx.MultiDiGraph()
+        self._search_graph_log = []
+        self._search_graph_n_replayed = 0
         self._index_cell_map = {}
         self._used_points = set()
         self._basis_indices = None
         self._pos_tol = None
         dict.__init__(self)
 
+    def add_search_edge(self, cell_index, seed_index, target_cell, match, multiplier):
+        """Records a link between two cells that was found during the search.
+
+        Creating the networkx graph is comparatively expensive and it is not
+        needed by all users. The links are therefore only recorded here and
+        the graph is created on demand when _search_graph is accessed.
+        """
+        self._search_graph_log.append(
+            (cell_index, seed_index, target_cell, match, multiplier)
+        )
+
+    @property
+    def _search_graph(self):
+        """A networkx.MultiDiGraph of the links between the cells that were
+        found during the search."""
+        G = self._search_graph_cache
+        log = self._search_graph_log
+        for i in range(self._search_graph_n_replayed, len(log)):
+            cell_index, seed_index, target_cell, match, multiplier = log[i]
+            G.add_node(cell_index, index=seed_index)
+            G.add_node(target_cell, index=match)
+            G.add_edge(cell_index, target_cell, multiplier=multiplier)
+        self._search_graph_n_replayed = len(log)
+        return G
+
     def __setitem__(self, key, value):
         # Transform key to tuple, check length
         try: