gridmlip 0.2__tar.gz → 0.2.3__tar.gz

{gridmlip-0.2 → gridmlip-0.2.3}/LICENSE

@@ -1,5 +1,4 @@
-
-Copyright (c) 2025 Artem Dembitskiy
+Copyright (c) 2025-2026 Artem D. Dembitskiy
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{gridmlip-0.2 → gridmlip-0.2.3}/MANIFEST.in

@@ -1,3 +1,2 @@
 include LICENSE
 include README.md
-

gridmlip-0.2.3/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.1
+Name: gridmlip
+Version: 0.2.3
+Summary: gridmlip
+Home-page: https://github.com/dembart/gridmlip
+Author: Artem Dembitskiy
+Author-email: art.dembitskiy@gmail.com
+License: MIT
+Keywords: MLIP,percolation barrier,irreducible mesh
+Classifier: License :: OSI Approved :: BSD License
+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
+Classifier: Programming Language :: Python :: 3.15
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+## gridmlip
+<p align="left">
+<a href="https://github.com/dembart/gridmlip/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-darkred"></a>
+
+
+## Contents
+- [About](#about)
+- [Installation](#installation)
+- [How to use](#how-to-use)
+- [Notebooks](#notebooks)
+- [How to cite](#how-to-cite)
+
+
+## About
+
+**gridmlip** is a library for the symmetry-aware grid-based sampling of the energy landscape of mobile species in solids using machine learning interatomic potentials (MLIPs).
+
+> (!) Note: The API and functionality may change. Errors are expected. The library is under development.
+
+## Installation
+
+```
+pip install gridmlip
+```
+or
+
+```python
+git clone https://github.com/dembart/gridmlip
+cd gridmlip
+pip install .
+```
+
+## How to use
+Here we describe the pipeline in general. For a specific example, see [Notebooks](#notebooks).
+
+### Percolation analysis
+
+```python 
+from gridmlip import Grid
+from gridmlip.integrations.sevennet import evaluate_atoms_list # sevenn must be installed
+
+file = './data/Li10Ge(PS6)2_mp.cif'
+specie = 3
+
+### Create grid
+g = Grid.from_file(
+    file,
+    specie,
+    r_min=0.8,
+    r_cut=5.0,
+    resolution=0.2,
+    symprec=0.1,
+    empty_framework=True,
+    verbose=True
+)
+
+### Prepare inequivalent atomic configurations
+atoms_list = g.construct_configurations(config_format='ase')
+
+### Predict energies
+energy_list, forces_list = evaluate_atoms_list(
+    atoms_list,
+    model_path='./data/checkpoint_sevennet_0.pth',
+    device='cuda',
+    compute_force=False,
+    batch_size=256
+)
+
+### Load energies
+g.load_energies(energy_list)
+
+### Determine percolation barriers
+barriers = g.percolation_barriers(n_jobs=-1)
+
+### Save .grd file for visualization in VESTA 3.0
+g.write_grd('test.grd')
+```
+### Generate defected configurations for MLIP pre-training
+
+```python
+from ase.io import read
+from gridmlip._generate import DefectGenerator
+
+GENERATOR_PARAMS = {
+    'specie': 3,
+    'resolution': 0.25,
+    'r_min': 1.3,
+    'r_cut': 7.5,
+    'symprec': 0.1,
+    'max_sep_dist': 'auto',
+    'upper_bound': 6.0,
+}
+
+gen = DefectGenerator(atoms, **GENERATOR_PARAMS)
+
+### Symmetrically distinct defect configurations
+cfgs_int = gen.generate_dataset(defect_type='int') 
+cfgs_vac= gen.generate_dataset(defect_type='vac')
+cfgs_frk = gen.generate_dataset(defect_type='frenkel')
+```
+
+## Notebooks
+
+
+- [Using SevenNet for calculating percolation barriers](notebooks/integrations.ipynb)    
+
+- [Using moment tensor potentials (as implemented in MLIP 2.0) for calculating percolation barriers](notebooks/mtp.ipynb)
+
+
+### How to cite
+If you use the gridmlip library, please, consider citing this repository.
+

gridmlip-0.2.3/README.md

@@ -0,0 +1,112 @@
+## gridmlip
+<p align="left">
+<a href="https://github.com/dembart/gridmlip/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-darkred"></a>
+
+
+## Contents
+- [About](#about)
+- [Installation](#installation)
+- [How to use](#how-to-use)
+- [Notebooks](#notebooks)
+- [How to cite](#how-to-cite)
+
+
+## About
+
+**gridmlip** is a library for the symmetry-aware grid-based sampling of the energy landscape of mobile species in solids using machine learning interatomic potentials (MLIPs).
+
+> (!) Note: The API and functionality may change. Errors are expected. The library is under development.
+
+## Installation
+
+```
+pip install gridmlip
+```
+or
+
+```python
+git clone https://github.com/dembart/gridmlip
+cd gridmlip
+pip install .
+```
+
+## How to use
+Here we describe the pipeline in general. For a specific example, see [Notebooks](#notebooks).
+
+### Percolation analysis
+
+```python 
+from gridmlip import Grid
+from gridmlip.integrations.sevennet import evaluate_atoms_list # sevenn must be installed
+
+file = './data/Li10Ge(PS6)2_mp.cif'
+specie = 3
+
+### Create grid
+g = Grid.from_file(
+    file,
+    specie,
+    r_min=0.8,
+    r_cut=5.0,
+    resolution=0.2,
+    symprec=0.1,
+    empty_framework=True,
+    verbose=True
+)
+
+### Prepare inequivalent atomic configurations
+atoms_list = g.construct_configurations(config_format='ase')
+
+### Predict energies
+energy_list, forces_list = evaluate_atoms_list(
+    atoms_list,
+    model_path='./data/checkpoint_sevennet_0.pth',
+    device='cuda',
+    compute_force=False,
+    batch_size=256
+)
+
+### Load energies
+g.load_energies(energy_list)
+
+### Determine percolation barriers
+barriers = g.percolation_barriers(n_jobs=-1)
+
+### Save .grd file for visualization in VESTA 3.0
+g.write_grd('test.grd')
+```
+### Generate defected configurations for MLIP pre-training
+
+```python
+from ase.io import read
+from gridmlip._generate import DefectGenerator
+
+GENERATOR_PARAMS = {
+    'specie': 3,
+    'resolution': 0.25,
+    'r_min': 1.3,
+    'r_cut': 7.5,
+    'symprec': 0.1,
+    'max_sep_dist': 'auto',
+    'upper_bound': 6.0,
+}
+
+gen = DefectGenerator(atoms, **GENERATOR_PARAMS)
+
+### Symmetrically distinct defect configurations
+cfgs_int = gen.generate_dataset(defect_type='int') 
+cfgs_vac= gen.generate_dataset(defect_type='vac')
+cfgs_frk = gen.generate_dataset(defect_type='frenkel')
+```
+
+## Notebooks
+
+
+- [Using SevenNet for calculating percolation barriers](notebooks/integrations.ipynb)    
+
+- [Using moment tensor potentials (as implemented in MLIP 2.0) for calculating percolation barriers](notebooks/mtp.ipynb)
+
+
+### How to cite
+If you use the gridmlip library, please, consider citing this repository.
+

gridmlip-0.2.3/gridmlip/_distortion.py

@@ -0,0 +1,44 @@
+import numpy as np
+
+
+def _get_rng(rng=None):
+    if isinstance(rng, np.random.Generator):
+        return rng
+    return np.random.default_rng(rng)
+
+
+def distort_lattice(atoms, std=0.03, rng=None):
+    """Randomly apply independent strain to the three lattice vectors."""
+    rng = _get_rng(rng)
+
+    cell = atoms.cell.array.copy()
+    lengths = np.linalg.norm(cell, axis=1)
+
+    scale = rng.uniform(
+        1 - std,
+        1 + std,
+        size=3,
+    )
+
+    new_lengths = lengths * scale
+    new_cell = cell * (new_lengths / lengths)[:, None]
+
+    distorted = atoms.copy()
+    distorted.info["original_cell"] = atoms.cell.array.copy()
+    distorted.set_cell(new_cell, scale_atoms=True)
+
+    return distorted
+
+
+def rattle_positions(atoms, std=0.05, rng=None):
+    """Randomly rattle atomic positions."""
+    rng = _get_rng(rng)
+
+    rattled = atoms.copy()
+    rattled.arrays["original_positions"] = (
+        rattled.positions.copy()
+    )
+
+    rattled.rattle(stdev=std, rng=rng)
+
+    return rattled

gridmlip-0.2.3/gridmlip/_generate.py

@@ -0,0 +1,251 @@
+import numpy as np
+from tqdm import tqdm
+
+from spglib import get_symmetry_dataset
+from ions import Percolator, Edge
+
+from .core import Grid
+from ._neighborhood import nn_list
+from ._distortion import rattle_positions, distort_lattice
+
+
+
+class DefectGenerator:
+
+    def __init__(
+        self,
+        atoms,
+        specie: int,
+        resolution: float = 0.25,
+        r_cut: float = 6.0,
+        r_min: float = 1.0,
+        symprec: float | None = 0.1,
+        max_sep_dist: float | str = 'auto',
+        upper_bound: float = 6.0,
+        verbose: bool = False,
+        seed: int | np.random.Generator | None = None,
+    ):
+        if specie is None:
+            raise ValueError("specie is required (atomic number of the mobile species)")
+
+        self.atoms = atoms.copy()
+        self.specie = specie
+        self.resolution = resolution
+        self.r_cut = r_cut
+        self.r_min = r_min
+        self.symprec = symprec
+        self.max_sep_dist = max_sep_dist
+        self.verbose = verbose
+        self.upper_bound = upper_bound
+        self._specie_symbol = atoms[atoms.numbers == specie].symbols[0]
+        self.rng = np.random.default_rng(seed)
+        self._percolator = None # placeholder
+        self._mincut_maxdim = None # placeholder
+
+
+    def _make_grid(self, atoms):
+        grid = Grid(
+            atoms,
+            specie=self.specie,
+            resolution=self.resolution,
+            symprec=self.symprec,
+            empty_framework=False,
+            r_cut=self.r_cut,
+            r_min=self.r_min,
+            verbose=self.verbose,
+        )
+        grid.generate_mesh()
+        return grid
+
+    @staticmethod
+    def _valid_positions(mesh_pos, framework, r_min):
+        """Filter candidate positions using the actual framework."""
+        if r_min <= 0:
+            return mesh_pos
+
+        distances, _ = nn_list(framework.positions, mesh_pos, r_cut=r_min, cell=framework.cell)
+
+        return mesh_pos[distances >= r_min]
+
+
+    @staticmethod
+    def _remove_atoms(atoms, indices):
+        mask = np.ones(len(atoms), dtype=bool)
+        mask[indices] = False
+        return atoms[mask].copy()
+
+
+    @staticmethod
+    def _filter_by_distance(mesh_pos, center, r_cut, cell):
+        """Keep points within cutoff of center."""
+        distances, _ = nn_list(center.reshape(1, 3), mesh_pos, r_cut=r_cut, cell=cell)
+        return mesh_pos[distances <= r_cut]
+
+
+    def _get_percolator(self):
+        """Note: bottleneck_radius is hardcoded to 0.0 here."""
+        if self._percolator is None:
+            pl = Percolator(self.atoms, mobile_specie=self._specie_symbol, upper_bound=self.upper_bound)
+            mincut, maxdim = pl.mincut_maxdim(bottleneck_radius=0.0)
+            self._percolator = pl
+            self._mincut_maxdim = (mincut, maxdim)
+        return (self._percolator, *self._mincut_maxdim)
+
+
+    def _prepare_site(self, atoms, base, remove_ids, center, max_sep):
+        grid = self._make_grid(self._remove_atoms(atoms, remove_ids))
+        ir_mesh_cart = grid.mesh_cart[grid.ir_grid_points]
+        filtered_pos = ir_mesh_cart[grid.min_dists >= grid.r_min]
+        filtered_pos = self._filter_by_distance(filtered_pos, center, max_sep, atoms.cell)
+        
+        # filtering due to the lower defect concentration in a supercell
+        defect_base = self._remove_atoms(base, remove_ids)
+        
+        filtered_pos = self._valid_positions(
+            filtered_pos,
+            defect_base[defect_base.numbers == self.specie],
+            self.r_min,
+        )
+        
+        return filtered_pos, defect_base
+
+
+    def _prepare_interstitials(self):
+
+        atoms = self.atoms.copy()
+        grid = self._make_grid(atoms)
+        base = grid._repeat_atoms(atoms, grid.r_cut)
+        ir_mesh_cart = grid.mesh_cart[grid.ir_grid_points]
+        filtered_pos = ir_mesh_cart[grid.min_dists >= grid.r_min]
+        return [(filtered_pos, base)]
+
+
+
+    def _prepare_vacancies(self):
+
+        atoms = self.atoms.copy()
+        pl, mincut, maxdim = self._get_percolator()
+        edges = pl.unique_edges(cutoff=mincut, bottleneck_radius=0.0)
+
+        base = Grid._repeat_atoms(atoms, self.r_cut)
+
+        sites_and_base = []
+        for edge_data in edges:
+
+            source, target, offset = (edge_data[0], edge_data[1], edge_data[2:])
+            scale = (atoms.cell.cellpar()[:3] / base.cell.cellpar()[:3])
+            edge = Edge(base, source, target, offset * scale)
+
+            local_max_sep = self.max_sep_dist
+            if local_max_sep == "auto":
+                local_max_sep = edge.length / 2 + self.resolution
+
+            filtered_pos, defect_base = self._prepare_site(
+                atoms, base, [source, target], edge.centroid, local_max_sep
+            )
+            sites_and_base.append((filtered_pos, defect_base))
+
+        return sites_and_base
+
+
+
+    def _prepare_frenkels(self):
+
+        atoms = self.atoms.copy()
+
+        equivalent_atoms = np.arange(len(atoms))
+        if self.symprec is not None:
+            dataset = get_symmetry_dataset(
+                (
+                    atoms.cell,
+                    atoms.get_scaled_positions(),
+                    atoms.numbers,
+                ),
+                symprec=self.symprec,
+            )
+            equivalent_atoms = dataset.equivalent_atoms
+
+        ineq_sites = np.unique(equivalent_atoms)
+        vac_ids = ineq_sites[atoms.numbers[ineq_sites] == self.specie]
+
+        if self.max_sep_dist == "auto":
+            _, mincut, _ = self._get_percolator()
+            global_max_sep = mincut
+        else:
+            global_max_sep = self.max_sep_dist
+
+        base = Grid._repeat_atoms(atoms, self.r_cut)
+
+        sites_and_base = []
+        for vac_id in vac_ids:
+            filtered_pos, defect_base = self._prepare_site(
+                atoms, base, [vac_id], atoms.positions[vac_id], global_max_sep
+            )
+            sites_and_base.append((filtered_pos, defect_base))
+        return sites_and_base
+
+
+    @staticmethod
+    def _statistics(sites_and_base):
+        summary = {
+            'points': sum([d[0].shape[0] for d in sites_and_base]),
+            'bases': len(sites_and_base),
+        }
+        return summary
+
+
+    def _append_configurations(self, base, mesh_pos, pos_std=None, strain_std=None, verbose=False):
+        """Construct configurations"""
+        configs = []
+    
+        for p in tqdm(mesh_pos, desc="creating configurations", disable=not verbose):
+            framework = base.copy()
+
+            if pos_std is not None:
+                framework = rattle_positions(framework, std=pos_std, rng=self.rng)  # rng added
+    
+            framework.append(self.specie)
+            framework.positions[-1] = p
+    
+            if strain_std is not None:
+                framework = distort_lattice(framework, std=strain_std, rng=self.rng)  # rng added
+    
+            configs.append(framework)
+    
+        return configs
+
+
+    def generate_dataset(
+        self,
+        defect_type: str,
+        pos_std: float | None = None,
+        strain_std: float | None = None,
+        verbose: bool = False,
+        dry_run: bool = False,
+    ):
+        if defect_type == 'int':
+            sites_and_base = self._prepare_interstitials()
+        elif defect_type == 'vac':
+            sites_and_base = self._prepare_vacancies()
+        elif defect_type == 'frenkel':
+            sites_and_base = self._prepare_frenkels()
+        else:
+            raise ValueError(
+                f"defect_type must be 'int', 'vac', or 'frenkel', got {defect_type!r}"
+            )
+
+        if dry_run:
+            return self._statistics(sites_and_base)
+
+        cfgs = []
+        for (mesh_pos, base) in sites_and_base:
+            cfgs.extend(
+                self._append_configurations(
+                    base,
+                    mesh_pos,
+                    pos_std=pos_std,
+                    strain_std=strain_std,
+                    verbose=verbose,
+                )
+            )
+        return cfgs

{gridmlip-0.2 → gridmlip-0.2.3}/gridmlip/_mesh.py

@@ -123,7 +123,6 @@ class Mesh:
         npoints = len(self.mesh)
         nsym = len(self.rotations)
         
-        lin_indices = self._index_to_linear(self.mesh)
         index_map = np.arange(npoints, dtype=int)
     
         all_images = self._apply_sym_ops()

{gridmlip-0.2 → gridmlip-0.2.3}/gridmlip/_neighborhood.py

@@ -3,32 +3,27 @@ import numpy as np
 from scipy.spatial import cKDTree
 
 
+def nn_list(atoms_pos, mesh_pos, r_cut, cell=None):
 
-def _scale_cell(cell, r_cut):
-    volume = cell.volume
-    scale_a = 2 * np.ceil(r_cut/(volume/np.linalg.norm(np.cross(cell[2, :], cell[1, :])))) + 1
-    scale_b = 2 * np.ceil(r_cut/(volume/np.linalg.norm(np.cross(cell[0, :], cell[2, :])))) + 1
-    scale_c = 2 * np.ceil(r_cut/(volume/np.linalg.norm(np.cross(cell[0, :], cell[1, :])))) + 1
-    return scale_a, scale_b, scale_c
-
-
-
-def nn_list(atoms_pos, mesh_pos, r_cut, cell = None):
-    
     if np.any(cell):
-        scale = _scale_cell(cell, r_cut)
+        volume = np.linalg.det(cell)
+        h1 = volume/np.linalg.norm(np.cross(cell[2, :], cell[1, :]))
+        h2 = volume/np.linalg.norm(np.cross(cell[0, :], cell[2, :]))
+        h3 = volume/np.linalg.norm(np.cross(cell[0, :], cell[1, :]))
+        scale = 2 * np.array(np.ceil(r_cut/np.array([h1, h2, h3])), dtype=int) + 1
         scales = []
         for s in scale:
             scales.append(np.arange(-(s // 2), s // 2 + 1))
+
         translations = tuple(list(itertools.product(
                                 scales[0],
                                 scales[1],
                                 scales[2])))   
         
-        buffer = (atoms_pos[:, None, :] + np.dot(translations, cell)).reshape(-1, 3, order = 'F')
+        buffer = (atoms_pos[:, None, :] + np.dot(translations, cell)).reshape(-1, 3, order='F')
     else:
         buffer = atoms_pos
 
     tree = cKDTree(buffer)
-    distances, indexes = tree.query(mesh_pos, workers=-1, k=1, distance_upper_bound = r_cut)      
+    distances, indexes = tree.query(mesh_pos, workers=-1, k=1, distance_upper_bound=r_cut)      
     return distances, indexes

{gridmlip-0.2 → gridmlip-0.2.3}/gridmlip/_percolation_analysis.py

@@ -167,7 +167,7 @@ class Percolyze:
 
 
     
-    def _percolation_energy(self, dim, encut = 10.0):
+    def _percolation_energy(self, dim, upper_limit=10.0):
 
         """
         Get percolation energy fofr a given dimensionality of percolation
@@ -178,7 +178,7 @@ class Percolyze:
         dim: int
             dimensionality of percolation. 2 -> 1D, 4 -> 2D, 8 - 3D percolation
             
-        encut: float, 10.0 by default
+        upper_limit: float, 10.0 by default
             stop criterion for the search of percolation energy
         
         Returns
@@ -190,7 +190,7 @@ class Percolyze:
         data = self.data.reshape(self.size)
         data = data - data.min()
         emin = data.min()
-        emax = emin + encut
+        emax = emin + upper_limit
         count = 0
         barrier = np.inf
         while (emax - emin) > 0.01:
@@ -210,7 +210,7 @@ class Percolyze:
 
 
 
-    def percolation_barriers(self, encut = 10.0, n_jobs = 1, backend = 'threading'):
+    def percolation_barriers(self, upper_limit=10.0, n_jobs=1, backend='threading'):
 
         """
         Find percolation energy and dimensionality of a migration network.
@@ -218,7 +218,7 @@ class Percolyze:
         Parameters
         ----------
 
-        encut: float, 5.0 by default
+        upper_limit: float, 5.0 by default
             cutoff energy above which barriers supposed to be np.inf
 
         n_jobs: int, 1 by default
@@ -231,7 +231,7 @@ class Percolyze:
         ----------
         
         energies: dict
-            infromation about percolation {'E_1D': float, 'E_2D': float, 'E_3D': float}
+            infromation about percolation {'e1d': float, 'e2d': float, 'e3d': float}
 
         """
 
@@ -241,7 +241,7 @@ class Percolyze:
         energies = {}
         for i, dim in enumerate([2, 4, 8]):
             
-            energy = self._percolation_energy(encut = encut, dim = dim)
-            energies.update({f'E_{i+1}D': energy})
+            energy = self._percolation_energy(upper_limit = upper_limit, dim = dim)
+            energies.update({f'e{i+1}d': energy})
         return energies
     

gridmlip-0.2.3/gridmlip/_version.py

@@ -0,0 +1 @@
+__version__ = "0.2.3"