cgkmc 0.0.2__tar.gz

cgkmc-0.0.2/.gitignore

@@ -0,0 +1,178 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+_build/
+scratch.py
+.kmc_cache/

cgkmc-0.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jacob Jeffries
+
+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.

cgkmc-0.0.2/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.4
+Name: cgkmc
+Version: 0.0.2
+Summary: Crystal Growth Kinetic Monte Carlo
+Project-URL: Homepage, https://github.com/jwjeffr/cgkmc
+License-Expression: MIT
+License-File: LICENSE
+Keywords: crystal,graph,growth,kmc,morphology,nanocrystal,surface
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Requires-Dist: numpy~=2.0.2
+Requires-Dist: scipy~=1.13.1
+Provides-Extra: dev
+Requires-Dist: hatchling~=1.27.0; extra == 'dev'
+Requires-Dist: mypy~=1.13.0; extra == 'dev'
+Requires-Dist: pdoc~=15.0.1; extra == 'dev'
+Requires-Dist: pytest~=8.0.2; extra == 'dev'
+Requires-Dist: ruff~=0.9.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# cgkmc
+
+[![Custom shields.io](https://img.shields.io/badge/docs-brightgreen?logo=github&logoColor=green&label=gh-pages)](https://jwjeffr.github.io/cgkmc/)
+
+[![PyPI version shields.io](https://img.shields.io/pypi/v/cgkmc.svg)](https://pypi.python.org/pypi/cgkmc/)
+[![PyPI pyversions shields.io](https://img.shields.io/pypi/pyversions/cgkmc.svg)](https://pypi.python.org/pypi/cgkmc/)
+
+## 💎 What is cgkmc?
+
+`cgkmc` is a package for performing crystal growth simulations using the 
+[Kinetic Monte Carlo](https://en.wikipedia.org/wiki/Kinetic_Monte_Carlo) method. `cgkmc`'s namesake is shorthand for
+Crystal Growth Kinetic Monte Carlo.
+
+## 📥 Installation
+
+```bash
+pip install cgkmc
+```
+
+📃 License
+
+`cgkmc` is released under the MIT License.

cgkmc-0.0.2/README.md

@@ -0,0 +1,22 @@
+# cgkmc
+
+[![Custom shields.io](https://img.shields.io/badge/docs-brightgreen?logo=github&logoColor=green&label=gh-pages)](https://jwjeffr.github.io/cgkmc/)
+
+[![PyPI version shields.io](https://img.shields.io/pypi/v/cgkmc.svg)](https://pypi.python.org/pypi/cgkmc/)
+[![PyPI pyversions shields.io](https://img.shields.io/pypi/pyversions/cgkmc.svg)](https://pypi.python.org/pypi/cgkmc/)
+
+## 💎 What is cgkmc?
+
+`cgkmc` is a package for performing crystal growth simulations using the 
+[Kinetic Monte Carlo](https://en.wikipedia.org/wiki/Kinetic_Monte_Carlo) method. `cgkmc`'s namesake is shorthand for
+Crystal Growth Kinetic Monte Carlo.
+
+## 📥 Installation
+
+```bash
+pip install cgkmc
+```
+
+📃 License
+
+`cgkmc` is released under the MIT License.

cgkmc-0.0.2/cgkmc/__init__.py

@@ -0,0 +1,23 @@
+"""
+.. include:: ../README.md
+
+# Examples
+
+## 📦 Simple cubic growth
+
+Below is an example of the growth of a small simple cubic lattice, printing a LAMMPS-style dump string
+
+```py
+.. include:: ../examples/simple_cubic.py
+```
+
+"""
+
+__version__ = "0.0.2"
+__authors__ = ["Jacob Jeffries"]
+__author_emails__ = ["jwjeffr@clemson.edu"]
+__url__ = "https://github.com/jwjeffr/cgkmc"
+
+from . import containers as containers
+from . import simulations as simulations
+from . import utils as utils

cgkmc-0.0.2/cgkmc/containers.py

@@ -0,0 +1,177 @@
+from dataclasses import dataclass
+from typing import Tuple, Optional
+import logging
+from pathlib import Path
+
+import numpy as np
+import scipy # type: ignore
+
+from .utils import array_to_hex
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class Solvent:
+    r"""
+    Solvent container class.
+    Temperature (or $\beta$), diffusivity, and solubility limit fully define the solvent.
+    $\beta$ should match the units of the interaction energies you specify.
+    See `utils.Units` class for available energy units, and use temp_to_beta() to get $\beta$ from temperature in K
+    """
+
+    beta: float
+    diffusivity: float
+    solubility_limit: float
+
+
+@dataclass
+class Growth:
+    """
+    Growth container class.
+    Mimics experimental controls, i.e. initial crystal size, amount of time we grow, and the final size we want.
+    """
+
+    initial_radius: float
+    num_steps: int
+    desired_size: int
+
+    @property
+    def initial_surface_area(self) -> float:
+        r"""
+        Shortcut property for computing surface area.
+        Crystal is assumed to be spherical, so surface area = $4\pi\times (\text{radius})^2$
+        """
+
+        return 4.0 * np.pi * self.initial_radius ** 2
+
+
+@dataclass
+class CubicLattice:
+    """
+    CubicLattice
+    """
+
+    dimensions: np.typing.NDArray[np.integer]
+    lattice_parameters: np.typing.NDArray[np.floating]
+    atomic_basis: np.typing.NDArray[np.floating]
+
+    def __post_init__(self):
+        # turn objects into tensors if they're not already tensors
+        if not isinstance(self.dimensions, np.ndarray):
+            self.dimensions = np.array(self.dimensions, dtype=int)
+        if not isinstance(self.lattice_parameters, np.ndarray):
+            self.lattice_parameters = np.array(self.lattice_parameters, dtype=float)
+        if not isinstance(self.atomic_basis, np.ndarray):
+            self.atomic_basis = np.array(self.atomic_basis, dtype=float)
+
+    @property
+    def density(self) -> float:
+
+        return self.atomic_basis.shape[0] / np.prod(self.lattice_parameters)
+
+    @property
+    def molecular_volume(self) -> float:
+
+        return 1.0 / self.density
+
+    def initialize_simulation(self) -> Tuple[np.typing.NDArray[np.floating], np.typing.NDArray[np.floating]]:
+
+        x = np.arange(self.dimensions[0]) * self.lattice_parameters[0]
+        y = np.arange(self.dimensions[1]) * self.lattice_parameters[1]
+        z = np.arange(self.dimensions[2]) * self.lattice_parameters[2]
+
+        x_grid, y_grid, z_grid = np.meshgrid(x, y, z, indexing='ij')
+        unit_cell_points = np.vstack([x_grid.ravel(), y_grid.ravel(), z_grid.ravel()]).T
+
+        lattice_points = unit_cell_points[:, None, :] + self.atomic_basis[None, :, :] * self.lattice_parameters
+        lattice_points = lattice_points.reshape(-1, 3)
+        bounds = self.lattice_parameters * self.dimensions
+
+        logger.debug("lattice sites initialized", extra={"num_sites": len(lattice_points), "bounds": bounds.tolist()})
+
+        return lattice_points, bounds
+
+
+@dataclass
+class KthNearest:
+
+    cutoffs: np.typing.NDArray[np.floating]
+    interaction_energies: np.typing.NDArray[np.floating]
+    maxint: Optional[int] = None
+    use_cache: Optional[bool] = False
+
+    def __post_init__(self):
+
+        if not self.maxint:
+            self.maxint = 10_000_000
+
+        if not isinstance(self.cutoffs, np.ndarray):
+            self.cutoffs = np.array(self.cutoffs)
+
+        if not isinstance(self.interaction_energies, np.ndarray):
+            self.interaction_energies = np.array(self.interaction_energies)
+
+    def compute_hamiltonian(
+        self,
+        lattice_points: np.typing.NDArray[np.floating],
+        bounds: np.typing.NDArray[np.floating]
+    ) -> scipy.sparse.csr_matrix:
+
+        tree = scipy.spatial.KDTree(lattice_points, leafsize=self.maxint, boxsize=bounds)
+
+        distance_matrix = tree.sparse_distance_matrix(tree, max_distance=self.cutoffs[-1]).tocsr()
+        distance_matrix.eliminate_zeros()
+
+        interaction_types = np.searchsorted(self.cutoffs, distance_matrix.data, side="left")
+        interaction_energies = self.interaction_energies[interaction_types]
+
+        return scipy.sparse.csr_matrix(
+            (interaction_energies, distance_matrix.indices, distance_matrix.indptr),
+            shape=distance_matrix.shape
+        )
+
+    def get_hamiltonian(
+        self,
+        lattice_points: np.typing.NDArray[np.floating],
+        bounds: np.typing.NDArray[np.floating]
+    ) -> scipy.sparse.csr_matrix:
+
+        if not self.use_cache:
+            hamiltonian = self.compute_hamiltonian(lattice_points, bounds)
+
+            logger.debug("hamiltonian initialized", extra={
+                "num_interactions": hamiltonian.nnz, "cohesive_energy": 0.5 * hamiltonian.sum(axis=0).mean()
+            })
+
+            return hamiltonian
+
+        cache_folder = Path(".kmc_cache")
+        cache_folder.mkdir(exist_ok=True)
+        hexes = [
+            array_to_hex(self.cutoffs),
+            array_to_hex(self.interaction_energies),
+            array_to_hex(lattice_points),
+            array_to_hex(bounds)
+        ]
+        hamiltonian_path = cache_folder / Path(f"{'_'.join(hexes)}.npz")
+
+        if not hamiltonian_path.exists():
+            hamiltonian = self.compute_hamiltonian(lattice_points, bounds)
+            scipy.sparse.save_npz(hamiltonian_path, hamiltonian)
+
+            logger.debug("hamiltonian initialized and saved", extra={
+                "num_interactions": hamiltonian.nnz, "cohesive_energy": 0.5 * hamiltonian.sum(axis=0).mean(),
+                "cache_path": hamiltonian_path.name
+            })
+
+            return hamiltonian
+
+        hamiltonian = scipy.sparse.load_npz(hamiltonian_path)
+
+        logger.debug("hamiltonian loaded from cache", extra={
+            "num_interactions": hamiltonian.nnz, "cohesive_energy": 0.5 * hamiltonian.sum(axis=0).mean(),
+            "cache_path": hamiltonian_path.name
+        })
+
+        return hamiltonian

cgkmc-0.0.2/cgkmc/simulations.py

@@ -0,0 +1,225 @@
+from dataclasses import dataclass, field
+from typing import Optional, Tuple, IO
+from functools import cached_property
+from io import StringIO
+import logging
+
+import numpy as np
+import scipy # type: ignore
+
+from .containers import Solvent, Growth, CubicLattice, KthNearest
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class Simulation:
+    """
+    Simulation class.
+    Main method is `Simulation.perform`, which performs a crystal growth simulation using Kinetic Monte Carlo
+    """
+
+    lattice: CubicLattice
+    interactions: KthNearest
+    solvent: Solvent
+    growth: Growth
+    seed: Optional[int] = None
+    generator: np.random.Generator = field(init=False)
+    lattice_points: np.typing.NDArray[np.floating] = field(init=False)
+    bounds: np.typing.NDArray[np.floating] = field(init=False)
+    surface_density: float = field(init=False)
+
+    def __post_init__(self):
+
+        self.seed = self.seed or 0
+        self.generator = np.random.default_rng(seed=self.seed)
+        self.lattice_points, self.bounds = self.lattice.initialize_simulation()
+
+    @cached_property
+    def hamiltonian(self) -> scipy.sparse.csr_matrix:
+
+        r"""
+        Defines the Hamiltonian matrix $\mathbf{Q}$, which defines the energy function:
+        $$E(x) = \frac{1}{2}\mathbf{x}^\intercal\mathbf{Q}\mathbf{x}$$
+        """
+
+        return self.interactions.get_hamiltonian(self.lattice_points, self.bounds)
+
+    @cached_property
+    def adjacency_matrix(self) -> scipy.sparse.csr_matrix:
+
+        r"""
+        Defines the adjacency matrix $\mathbf{A}$, where $A_{ij} = 1$ if sites $i$ and $j$ have an interaction.
+        """
+
+        return scipy.sparse.csr_matrix(
+            (np.ones_like(self.hamiltonian.data), self.hamiltonian.indices, self.hamiltonian.indptr),
+            shape=self.hamiltonian.shape
+        )
+
+    @cached_property
+    def num_neighbors(self) -> int:
+
+        num_neighbors_per_site = self.adjacency_matrix.sum(axis=0)
+        if not np.isclose(num_neighbors_per_site.std(), 0.0):
+            raise ValueError("non-periodic lattice")
+        return num_neighbors_per_site.mean()
+
+    def get_lammps_dump_str(self, types: np.typing.NDArray[np.floating], step: int, t: float) -> str:
+
+        """
+        Shortcut method for getting a LAMMPS-style dump str, which looks like:
+
+        ```
+        ITEM: TIMESTEP
+        0 0.0
+        ITEM: NUMBER OF ATOMS
+        1874
+        ITEM: BOX BOUNDS xy xz xx yy zz
+        0.0 318.08 0.0
+        0.0 318.08 0.0
+        0.0 303.165 0.0
+        ITEM: ATOMS id type x y z
+        39105 1 113.6000 131.7760 151.5825
+        39189 1 113.6000 140.8640 131.3715
+        39191 1 113.6000 140.8640 138.1085
+        39193 1 113.6000 140.8640 144.8455
+        39195 1 113.6000 140.8640 151.5825
+        39197 1 113.6000 140.8640 158.3195
+        ...
+        ```
+
+        at each timestep
+        """
+
+        mask = types == 1
+
+        ids = np.arange(len(self.lattice_points))
+        occupied_ids = ids[mask].reshape(-1, 1)
+        occupied_sites = self.lattice_points[mask, :]
+
+        header = "\n".join([
+            "ITEM: TIMESTEP",
+            f"{step:.0f} {t}",
+            "ITEM: NUMBER OF ATOMS",
+            f"{len(occupied_ids):.0f}",
+            "ITEM: BOX BOUNDS xy xz xx yy zz",
+            f"0.0 {self.bounds[0]} 0.0",
+            f"0.0 {self.bounds[1]} 0.0",
+            f"0.0 {self.bounds[2]} 0.0",
+            "ITEM: ATOMS id type x y z"
+        ])
+
+        data = np.concatenate((occupied_ids, np.ones_like(occupied_ids), occupied_sites), axis=1)
+
+        with StringIO() as string_io:
+            np.savetxt(string_io, data, fmt=("%.0f", "%.0f", "%.4f", "%.4f", "%.4f"), comments="", header=header) # type: ignore
+            return string_io.getvalue()
+
+    @property
+    def kappa(self) -> float:
+
+        r"""
+        Shorthand when computing dynamic evaporation prefactor, i.e.:
+
+        $$\nu_t = \kappa / \left\langle \exp\left(\beta\Delta E_\text{evap}\right)\right\rangle$$
+        """
+
+        # only defined if the surface density has been calculated or not
+        if not hasattr(self, "surface_density"):
+            raise ValueError("surface density not yet calculated")
+
+        return (4.0 / 3.0 * np.pi * self.lattice.density) ** (1 / 3) * self.solvent.diffusivity * \
+            self.solvent.solubility_limit / (self.surface_density * self.growth.desired_size ** (1 / 3))
+
+    def get_interface(
+        self,
+        types: np.typing.NDArray[np.floating]
+    ) -> Tuple[np.typing.NDArray[np.integer], np.typing.NDArray[np.integer]]:
+
+        """
+        Function for computing interfacial solvent and solid sites.
+        Ax counts the number of currently occupied neighbors.
+        """
+
+        occupied_neighbor_count = self.adjacency_matrix @ types
+        solid_sites, = np.where(types * (self.num_neighbors - occupied_neighbor_count) > 0)
+        solvent_sites, = np.where((1.0 - types) * occupied_neighbor_count > 0)
+
+        return solid_sites, solvent_sites
+
+    def perform(self, dump_file: IO, dump_every: int):
+
+        """
+        Main method for performing a Kinetic Monte Carlo simulation. This is performable by calling something like:
+
+        ```py
+        simulation = Simulation(...)
+        with open("kmc.dump", "w") as file:
+            simulation.perform(dump_file=file, dump_every=100)
+        ```
+
+        or any other IO-like object, such as StringIO or BytesIO
+        """
+
+        # initialize a spherical crystal with specified radius
+        center = self.lattice_points.mean(axis=0)
+        types = (np.linalg.norm(self.lattice_points - center, axis=1) <= self.growth.initial_radius).astype(float)
+
+        solid_sites, _ = self.get_interface(types)
+        self.surface_density = len(solid_sites) / self.growth.initial_surface_area
+
+        t = 0.0
+        total_energy = 0.5 * types.T @ self.hamiltonian @ types
+        for step in range(self.growth.num_steps):
+
+            # if types.mean() is 0, entire cell is unoccupied, so no simulation
+            # similarly, if types.mean() is 1, entire cell is occupied
+            occupancy = types.mean()
+            if not 0.0 < occupancy < 1.0:
+                logging.error("simulation killed, no interface detected")
+                return
+
+            # only want dumps at a small frequency
+            if not step % dump_every:
+                positions = self.get_lammps_dump_str(types, step, t)
+                print(positions, file=dump_file, end="")
+                logging.info("simulation info", extra={
+                    "step": step, "t": t, "total_energy": total_energy, "occupancy": occupancy
+                })
+                dump_file.flush()
+
+            solid_sites, solvent_sites = self.get_interface(types)
+
+            # need to rescale evaporation rates after calculating
+            # this is the dynamically updated prefactor
+            evaporation_barriers = -self.hamiltonian[solid_sites, :] @ types
+            evaporation_rates = np.exp(-self.solvent.beta * evaporation_barriers)
+            rate_prefactor = self.kappa / evaporation_rates.mean()
+            evaporation_rates = rate_prefactor * evaporation_rates
+
+            radius = (0.75 * self.lattice.molecular_volume * types.sum() / np.pi) ** (1 / 3)
+            adsorption_rates = np.ones_like(solvent_sites) * self.solvent.diffusivity * \
+                self.solvent.solubility_limit / (self.surface_density * radius)
+
+            # concatenate events, so we can pick event according to residence time algorithm
+            events = np.concatenate((solid_sites, solvent_sites))
+            rates = np.concatenate((evaporation_rates, adsorption_rates))
+            total_rate = rates.sum()
+
+            # pick event and advance time according to residence time algorithm
+            event = self.generator.choice(events, p=rates / total_rate)
+
+            # if there was an evaporation event, we've already computed \Delta E_evap
+            if types[event]:
+                change_in_energy_evap = evaporation_barriers[np.where(events == event)].item()
+                total_energy += change_in_energy_evap
+            # if it was an adsorption event, need to compute it
+            elif not types[event]:
+                change_in_energy_evap = -(self.hamiltonian[event, :] @ types).item()
+                total_energy += -change_in_energy_evap
+            else:
+                raise ValueError
+
+            types[event] = 1.0 - types[event]
+            t += self.generator.exponential(scale=1.0 / total_rate)

cgkmc-0.0.2/cgkmc/utils.py

@@ -0,0 +1,56 @@
+from enum import Enum, auto
+from hashlib import sha1
+
+import numpy as np
+
+
+class Units(Enum):
+    """
+    Available units. See https://docs.lammps.org/units.html for details
+    """
+
+    real = auto()
+    metal = auto()
+    si = auto()
+    cgs = auto()
+    electron = auto()
+    micro = auto()
+    nano = auto()
+
+    def boltzmann_constant(self):
+
+        if self == Units.real:
+            return 1.987e-3
+
+        if self == Units.metal:
+            return 8.617e-5
+
+        if self == Units.si:
+            return 1.381e-23
+
+        if self == Units.cgs:
+            return 1.381e-16
+
+        if self == Units.electron:
+            return 3.167e-6
+
+        if self == Units.micro:
+            return 1.381e-6
+
+        if self == Units.nano:
+            return 1.381e-2
+
+        raise ValueError("invalid unit system")
+
+
+def temp_to_beta(temperature: float, units: Units):
+    r"""
+    helper class to convert temperature to thermodynamic $\beta$ for a given choice of units
+    """
+
+    return 1.0 / (units.boltzmann_constant() * temperature)
+
+
+def array_to_hex(x: np.typing.NDArray[np.floating]) -> str:
+
+    return sha1(x.tobytes()).hexdigest()

cgkmc-0.0.2/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cgkmc"
+dynamic = ["version"]
+description = "Crystal Growth Kinetic Monte Carlo"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+author = { name = "Jacob Jeffries", email = "jwjeffr@clemson.edu" }
+keywords = [
+    "kmc",
+    "crystal",
+    "nanocrystal",
+    "morphology",
+    "graph",
+    "surface",
+    "growth"
+]
+classifiers = [
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "numpy ~= 2.0.2",
+    "scipy ~= 1.13.1"
+]
+
+[project.urls]
+Homepage = "https://github.com/jwjeffr/cgkmc"
+
+[project.optional-dependencies]
+dev = [
+    "hatchling~=1.27.0",
+    "pytest~=8.0.2",
+    "ruff~=0.9.4",
+    "mypy~=1.13.0",
+    "pdoc~=15.0.1"
+]
+
+[tool.hatch.version]
+path = "cgkmc/__init__.py"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/cgkmc",
+]