kmcpy 0.1.0__tar.gz

kmcpy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Caneparesearch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kmcpy-0.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: kmcpy
+Version: 0.1.0
+Summary: Kinetic Monte Carlo Simulation using Python (kMCpy)
+Author-email: kMCpy Development Team <dengzeyu@gmail.com>
+Maintainer-email: Zeyu Deng <dengzeyu@gmail.com>, Weihang Xie <david.xie1998@gmail.com>, Pieremanuele Canepa <pieremanuele.canepa@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2021 Caneparesearch
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/caneparesearch/kmcpy
+Project-URL: Repository, https://github.com/caneparesearch/kmcpy
+Project-URL: Issues, https://github.com/caneparesearch/kmcpy/issues
+Project-URL: Documentation, https://kmcpy.readthedocs.io/
+Keywords: kinetic monte carlo,kmc,simulation,materials science,condensed matter physics,chemistry
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: glob2>=0.7
+Requires-Dist: joblib>=1.5.1
+Requires-Dist: numba>=0.61.2
+Requires-Dist: pymatgen>=2025.5.2
+Requires-Dist: scikit-learn>=1.6.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Provides-Extra: doc
+Requires-Dist: sphinx>=7.0; extra == "doc"
+Requires-Dist: sphinx-rtd-theme; extra == "doc"
+Requires-Dist: nbsphinx; extra == "doc"
+Requires-Dist: sphinx-autodoc-typehints; extra == "doc"
+Requires-Dist: myst-parser; extra == "doc"
+Requires-Dist: tqdm; extra == "doc"
+Requires-Dist: psutil; extra == "doc"
+Dynamic: license-file
+
+# Kinetic Monte Carlo Simulation using Python (kMCpy)
+![image](docs/source/_static/kmcpy_logo.png)
+- Author: Zeyu Deng
+- Email: dengzeyu@gmail.com
+
+kMCpy is an open source python based package intended to study the migration of atoms using the kinetic Monte Carlo technique. kMCpy provides an all python, systematic way to compute kinetic properties, which can be readily used for investigation, development, and prediction of new functional materials. 
+
+This package includes a local cluster expansion model toolkit, a rejection-free kinetic Monte Carlo (rf-kMC) solver, and several python classes to extract ion transport properties such as diffusivities and conductivities. 
+
+The local cluster expansion model toolkit can be used to fit a model from barrier calculated from first-principles or any other empirical methods. Following the training process the local cluster expansion model can compute migration barriers in crystalline materials within the transition state theory.
+
+Some of the advantages of using this package are:
+
+1. kMCpy is fully based on python and is modular which makes it developer centric thus facilitating quick addition of new features.
+
+2. It is cross-platform and supports most operating systems such as Windows, macOS, and Linux.
+
+3. Intensive kMC routines has been optimized into machine code in the fly using Numba (https://numba.pydata.org), which results in manifold increase in performance. 
+
+
+This code has been recently used to explore the transport properties of Na-ion in NaSICON solid electrolyte (https://www.nature.com/articles/s41467-022-32190-7).
+Some of the relevant aspects of the code from the mentioned paper are shown below. 
+
+The rf-kMC as a part of this code was used to model the Na-ion conductivity in the $\mathrm{Na_{1+x}Zr_{2}Si_{x}P_{3-x}O_{12}}$ which led to the discovery of maximum conductivity of the solid electrolyte is achieved for Na=3.4.
+
+![image](docs/source/_static/computed_conductivity.png)
+
+   Calculated Na+ diffusivity (a), conductivity (b), Haven's ratio (c) and averaged correlation factor (d) of $\mathrm{Na_{1+x}Zr_{2}Si_{x}P_{3-x}O_{12}}$ at several temperatures: 373 (dark blue circles), 473 (orange squares) and 573 (red triangles) K, respectively. In panel (b), the computed ionic conductivities are compared with the experimental values of this work (Supplementary Fig. 6) at selected temperatures. Experimental values in (b) from this work are depicted with light blue (373 K), yellow (473 K), and red (573 K) crosses belonging to the same $\mathrm{Na_{1+x}Zr_{2}Si_{x}P_{3-x}O_{12}}$ compositions but of pellets with different compacities (>70 and >90%, see legend).
+
+# Installation
+## Prerequisite
+Check `pyproject.toml` for the required packages. The following Python packages are required to run kMCpy:
+- pymatgen: **Windows users need to install Microsoft C++ build tools (https://visualstudio.microsoft.com/visual-cpp-build-tools/) to compile pymatgen.**
+- numba: for fast computation of kMCpy routines
+- scikit-learn: for fitting local cluster expansion model
+- pytest: for unit tests
+- joblib
+- glob2
+
+> **⚠️ Warning for Windows users:**  
+> You need to install [Microsoft C++ build tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) to compile `pymatgen`.
+
+## Command line environment
+It is highly recommended to install kMCpy using [UV](https://docs.astral.sh/uv/getting-started/installation/) and use it with virtual environment.
+
+```shell
+uv venv #optional if you have already created a venv
+source .venv/bin/activate
+uv sync
+uv pip install .
+```
+
+## For developers 
+```shell
+uv venv #optional if you have already created a venv
+source .venv/bin/activate
+uv sync --extra dev
+uv pip install -e .
+```
+
+## Graphic user interface (GUI)
+`wxpython` needs `conda` to be installed.
+```shell
+conda create -n kmcpy python wxpython -c conda-forge
+conda activate kmcpy
+pip install -r requirement_gui.txt .
+```
+
+## Build documentation
+- Documentation is built using `pandoc` and `sphinx-build`.
+- You can access the documentation from: `./docs/html/index.html`.
+```shell
+source .venv/bin/activate
+uv sync --extra doc
+python build_doc.py
+```
+
+# Run kMCpy
+It is recommended to run kMCpy using the API. See examples for more details. A wrapper is also provided if you want to run kMCpy through command line only. 
+
+- If GUI enabled: try `pythonw gui_wrapper.py` or `python gui_wrapper`
+- If GUI not enabled: `wrapper.py PATH_TO_INPUT.json`

kmcpy-0.1.0/README.md

@@ -0,0 +1,82 @@
+# Kinetic Monte Carlo Simulation using Python (kMCpy)
+![image](docs/source/_static/kmcpy_logo.png)
+- Author: Zeyu Deng
+- Email: dengzeyu@gmail.com
+
+kMCpy is an open source python based package intended to study the migration of atoms using the kinetic Monte Carlo technique. kMCpy provides an all python, systematic way to compute kinetic properties, which can be readily used for investigation, development, and prediction of new functional materials. 
+
+This package includes a local cluster expansion model toolkit, a rejection-free kinetic Monte Carlo (rf-kMC) solver, and several python classes to extract ion transport properties such as diffusivities and conductivities. 
+
+The local cluster expansion model toolkit can be used to fit a model from barrier calculated from first-principles or any other empirical methods. Following the training process the local cluster expansion model can compute migration barriers in crystalline materials within the transition state theory.
+
+Some of the advantages of using this package are:
+
+1. kMCpy is fully based on python and is modular which makes it developer centric thus facilitating quick addition of new features.
+
+2. It is cross-platform and supports most operating systems such as Windows, macOS, and Linux.
+
+3. Intensive kMC routines has been optimized into machine code in the fly using Numba (https://numba.pydata.org), which results in manifold increase in performance. 
+
+
+This code has been recently used to explore the transport properties of Na-ion in NaSICON solid electrolyte (https://www.nature.com/articles/s41467-022-32190-7).
+Some of the relevant aspects of the code from the mentioned paper are shown below. 
+
+The rf-kMC as a part of this code was used to model the Na-ion conductivity in the $\mathrm{Na_{1+x}Zr_{2}Si_{x}P_{3-x}O_{12}}$ which led to the discovery of maximum conductivity of the solid electrolyte is achieved for Na=3.4.
+
+![image](docs/source/_static/computed_conductivity.png)
+
+   Calculated Na+ diffusivity (a), conductivity (b), Haven's ratio (c) and averaged correlation factor (d) of $\mathrm{Na_{1+x}Zr_{2}Si_{x}P_{3-x}O_{12}}$ at several temperatures: 373 (dark blue circles), 473 (orange squares) and 573 (red triangles) K, respectively. In panel (b), the computed ionic conductivities are compared with the experimental values of this work (Supplementary Fig. 6) at selected temperatures. Experimental values in (b) from this work are depicted with light blue (373 K), yellow (473 K), and red (573 K) crosses belonging to the same $\mathrm{Na_{1+x}Zr_{2}Si_{x}P_{3-x}O_{12}}$ compositions but of pellets with different compacities (>70 and >90%, see legend).
+
+# Installation
+## Prerequisite
+Check `pyproject.toml` for the required packages. The following Python packages are required to run kMCpy:
+- pymatgen: **Windows users need to install Microsoft C++ build tools (https://visualstudio.microsoft.com/visual-cpp-build-tools/) to compile pymatgen.**
+- numba: for fast computation of kMCpy routines
+- scikit-learn: for fitting local cluster expansion model
+- pytest: for unit tests
+- joblib
+- glob2
+
+> **⚠️ Warning for Windows users:**  
+> You need to install [Microsoft C++ build tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) to compile `pymatgen`.
+
+## Command line environment
+It is highly recommended to install kMCpy using [UV](https://docs.astral.sh/uv/getting-started/installation/) and use it with virtual environment.
+
+```shell
+uv venv #optional if you have already created a venv
+source .venv/bin/activate
+uv sync
+uv pip install .
+```
+
+## For developers 
+```shell
+uv venv #optional if you have already created a venv
+source .venv/bin/activate
+uv sync --extra dev
+uv pip install -e .
+```
+
+## Graphic user interface (GUI)
+`wxpython` needs `conda` to be installed.
+```shell
+conda create -n kmcpy python wxpython -c conda-forge
+conda activate kmcpy
+pip install -r requirement_gui.txt .
+```
+
+## Build documentation
+- Documentation is built using `pandoc` and `sphinx-build`.
+- You can access the documentation from: `./docs/html/index.html`.
+```shell
+source .venv/bin/activate
+uv sync --extra doc
+python build_doc.py
+```
+
+# Run kMCpy
+It is recommended to run kMCpy using the API. See examples for more details. A wrapper is also provided if you want to run kMCpy through command line only. 
+
+- If GUI enabled: try `pythonw gui_wrapper.py` or `python gui_wrapper`
+- If GUI not enabled: `wrapper.py PATH_TO_INPUT.json`

kmcpy-0.1.0/kmcpy/__init__.py

@@ -0,0 +1,64 @@
+"""Main kMCpy module."""
+import datetime
+import logging
+import os
+
+from ._version import __version__
+
+__author__ = "Zeyu Deng"
+__author_email__ = "dengzeyu@gmail.com"
+
+# Expose the version and the logo function as the public API for this module.
+__all__ = ["__version__", "get_logo"]
+
+
+# 2. LOGGING SETUP: This is perfect.
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+
+# 3. LOGO FUNCTION: A stateless function to generate and print the logo.
+
+def get_logo():
+    """
+    Prints the kMCpy ASCII logo and version/citation information to the console.
+
+    This function can be called multiple times. It's recommended to call
+    it once at the start of an application's main entry point.
+    """
+    # Ansi color codes for a professional look.
+    class Colors:
+        CYAN = '\033[96m'
+        YELLOW = '\033[93m'
+        BOLD = '\033[1m'
+        END = '\033[0m'
+
+    # The logo art. Using a raw string (r"...") is good practice.
+    logo_art = r"""
+  _    __  __  _____             
+ | |  |  \/  |/ ____|            
+ | | _| \  / | |     _ __  _   _ 
+ | |/ / |\/| | |    | '_ \| | | |
+ |   <| |  | | |____| |_) | |_| |
+ |_|\_\_|  |_|\_____| .__/ \__, |
+                    | |     __/ |
+                    |_|    |___/ 
+"""
+    
+    # Using os.uname() is not cross-platform (it fails on Windows).
+    # platform.node() is a more robust alternative.
+    import platform
+    hostname = platform.node()
+
+    # Assemble the final message string inside the function.
+    # This ensures all information (like datetime) is current.
+    message = (
+        f"{Colors.CYAN}{Colors.BOLD}{logo_art}{Colors.END}"
+        f"kMCpy: A python package to simulate transport properties in solids with kinetic Monte Carlo\n"
+        f"{Colors.YELLOW}Please cite:{Colors.END} DOI: 10.1016/j.commatsci.2023.112394 and 10.1038/s41467-022-32190-7 \n"
+        f"{Colors.YELLOW}Author:{Colors.END} {__author__} <{__author_email__}>\n"
+        f"Version: {__version__}\n"
+        f"Timestamp: {datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n"
+        f"Host: {hostname}\n"
+    )
+    
+    return message

kmcpy-0.1.0/kmcpy/_version.py

@@ -0,0 +1,3 @@
+__all__ = ["__version__"]
+
+__version__ = "0.1dev"

kmcpy-0.1.0/kmcpy/event.py

@@ -0,0 +1,173 @@
+#!/usr/bin/env python
+"""
+This module defines the Event class, which encapsulates the information and methods required to represent and analyze a migration event in a lattice-based simulation, such as those used in kinetic Monte Carlo (kMC) studies. The Event class manages indices of mobile ions, local environments, sublattice information, and provides methods for initializing, updating, and serializing event data. It also includes methods for calculating occupation, correlation, migration barriers, and probabilities associated with migration events.
+"""
+
+import numpy as np
+import numba as nb
+from copy import deepcopy
+import json
+from kmcpy.io import convert
+import logging
+
+logger = logging.getLogger(__name__) 
+logging.getLogger('numba').setLevel(logging.WARNING)
+
+class Event:
+    """
+    mobile_ion_specie_1_index
+    mobile_ion_specie_2_index
+    local_env_indices_list
+    """
+
+    def __init__(self):
+        pass
+
+    def initialization(
+        self,
+        mobile_ion_specie_1_index=12,
+        mobile_ion_specie_2_index=15,
+        local_env_indices_list=[1, 2, 3, 4, 5],
+    ):
+        """3rd version of initialization. The input local_env_indices_list is already sorted. Center atom is equivalent to the Na1 in the 1st version and mobile_ion_specie_2_index is equivalent to the Na2 in the 1st version
+
+        Args:
+            mobile_ion_specie_1_index (int, optional): the global index (index in supercell) of the center atom. Defaults to 12.
+            mobile_ion_specie_2_index (int, optional): the global index of the atom that the center atom is about to diffuse to. Defaults to 15.
+            local_env_indices_list (list, optional): list of integers, which is a list of indices of the neighboring sites in supercell, and is already sorted. Defaults to [1,2,3,4,5].
+        """
+        self.mobile_ion_specie_1_index = mobile_ion_specie_1_index
+        self.mobile_ion_specie_2_index = mobile_ion_specie_2_index
+
+        self.local_env_indices_list = local_env_indices_list
+        self.local_env_indices_list_site = local_env_indices_list
+
+    def set_sublattice_indices(self, sublattice_indices, sublattice_indices_site):
+        self.sublattice_indices = sublattice_indices  # this stores the site indices from local_cluster_expansion object
+        self.sublattice_indices_site = sublattice_indices_site  # this stores the site indices from local_cluster_expansion object
+
+    def show_info(self):
+        logger.info(
+            "Event: mobile_ion(1)[%s]<--> mobile_ion(2)[%s]",
+            self.mobile_ion_specie_1_index,
+            self.mobile_ion_specie_2_index,
+        )
+        logger.debug('Global sites indices are (excluding O and Zr): %s', self.local_env_indices_list)
+        logger.debug('Local template structure: %s', getattr(self, 'sorted_local_structure', None))
+
+        try:
+            logger.info("occ_sublat\tE_KRA\tProbability")
+            logger.info("%s\t%s\t%s", self.occ_sublat, self.ekra, self.probability)
+        except Exception:
+            pass
+
+    def clear_property(self):
+        pass
+
+    def analyze_local_structure(self, local_env_info):
+        #
+        indices_sites_group = [(s["site_index"], s["site"]) for s in local_env_info]
+
+        # this line is to sort the neighbors. First sort by x coordinate, and then sort by specie (Na, then Si/P)
+        # the sorted list, store the sequence of hash.
+        # for other materials, need to find another method to sort.
+        # this sort only works for the NaSICON!
+        indices_sites_group_sorted = sorted(
+            sorted(indices_sites_group, key=lambda x: x[1].coords[0]),
+            key=lambda x: x[1].specie,
+        )
+
+        local_env_indices_list = [s[0] for s in indices_sites_group_sorted]
+        return local_env_indices_list
+
+    # @profile
+    def set_occ(self, occ_global):
+        self.occ_sublat = deepcopy(
+            occ_global[self.local_env_indices_list]
+        )  # occ is an 1D numpy array
+
+    # @profile
+    def initialize_corr(self):
+        self.corr = np.empty(shape=len(self.sublattice_indices))
+        self.corr_site = np.empty(shape=len(self.sublattice_indices_site))
+
+    # @profile
+    def set_corr(self):
+        _set_corr(self.corr, self.occ_sublat, self.sublattice_indices)
+        _set_corr(self.corr_site, self.occ_sublat, self.sublattice_indices_site)
+
+    # @profile
+    def set_ekra(
+        self, keci, empty_cluster, keci_site, empty_cluster_site
+    ):  # input is the keci and empty_cluster; ekra = corr*keci + empty_cluster
+        self.ekra = np.inner(self.corr, keci) + empty_cluster
+        self.esite = np.inner(self.corr_site, keci_site) + empty_cluster_site
+
+    # @profile
+    def set_probability(
+        self, occ_global, v, T
+    ):  # calc_probability() will evaluate migration probability for this event, should be updated everytime when change occupation
+        k = 8.617333262145 * 10 ** (-2)  # unit in meV/K
+        direction = (
+            occ_global[self.mobile_ion_specie_2_index]
+            - occ_global[self.mobile_ion_specie_1_index]
+        ) / 2  # 1 if na1 -> na2, -1 if na2 -> na1
+        self.barrier = self.ekra + direction * self.esite / 2  # ekra
+        self.probability = abs(direction) * v * np.exp(-1 * (self.barrier) / (k * T))
+
+    # @profile
+    def update_event(
+        self, occ_global, v, T, keci, empty_cluster, keci_site, empty_cluster_site
+    ):
+        self.set_occ(occ_global)  # change occupation and correlation for this unit
+        self.set_corr()
+        self.set_ekra(
+            keci, empty_cluster, keci_site, empty_cluster_site
+        )  # calculate ekra and probability
+        self.set_probability(occ_global, v, T)
+
+    def as_dict(self):
+        d = {
+            "mobile_ion_specie_1_index": self.mobile_ion_specie_1_index,
+            "mobile_ion_specie_2_index": self.mobile_ion_specie_2_index,
+            "local_env_indices_list": self.local_env_indices_list,
+            "local_env_indices_list": self.local_env_indices_list,
+            "local_env_indices_list_site": self.local_env_indices_list_site,
+        }
+        return d
+
+    def to_json(self, fname):
+        logger.info("Saving: %s", fname)
+        with open(fname, "w") as fhandle:
+            d = self.as_dict()
+            jsonStr = json.dumps(
+                d, indent=4, default=convert
+            )  # to get rid of errors of int64
+            fhandle.write(jsonStr)
+
+    @classmethod
+    def from_json(self, fname):
+        logger.info("Loading: %s", fname)
+        with open(fname, "rb") as fhandle:
+            objDict = json.load(fhandle)
+        obj = Event()
+        obj.__dict__ = objDict
+        return obj
+    @classmethod
+    def from_dict(self, event_dict):  # convert dict into event object
+        event = Event()
+        event.__dict__ = event_dict
+        return event
+
+
+@nb.njit
+def _set_corr(corr, occ_latt, sublattice_indices):
+    i = 0
+    for sublat_ind_orbit in sublattice_indices:
+        corr[i] = 0
+        for sublat_ind_cluster in sublat_ind_orbit:
+            corr_cluster = 1
+            for occ_site in sublat_ind_cluster:
+                corr_cluster *= occ_latt[occ_site]
+            corr[i] += corr_cluster
+        i += 1