Merge pull request #17 from mcgalcode/dev

Dev

LICENSE

@@ -1,5 +1,5 @@
 The MIT License (MIT)
-Copyright (c) 2011-2012 MIT & The Regents of the University of California,
+Copyright (c) 2023-2024 MIT & The Regents of the University of California,
 through Lawrence Berkeley National Laboratory
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of

mkdocs.yml

@@ -60,7 +60,6 @@ nav:
       - SquareGridArtist2D: reference/visualization/square_grid_artist_2D.md
       - SquareGridArtist3D: reference/visualization/square_grid_artist_3D.md
       - ResultArtist: reference/visualization/result_artist.md
-  - CHANGELOG: ../CHANGELOG.md
 
 repo_url: https://github.com/mcgalcode/pylattica/
 repo_name: Github

paper/paper.md

@@ -29,13 +29,13 @@ bibliography: paper.bib
 
 # Statement of need
 
-Cellular automata [@bays_introduction_2010], lattice-gas automata [@boghosian_lattice_1999], and atomistic Monte Carlo models [@andersen_practical_2019] are all simulations in which a system, represented by an arrangement of connected sites, evolves over time according to an update rule which determines the future state of a site by considering its current state and the state of its neighbors. For example, in the classic "Game of Life" cellular automaton [@gardner_mathematical_1970], sites in a 2D square grid switch between "dead" and "alive" during each timestep based on the number of living neighbors surrounding them. In lattice Monte Carlo simulations for vacancy diffusion in crystalline solid materials, atoms move between neighboring sites at rates partially determined by the occupancy of their neighbors [@haley_vacancy_2006].
+Cellular automata [@bays_introduction_2010], lattice-gas automata [@boghosian_lattice_1999], and atomistic Monte Carlo models [@andersen_practical_2019] are all simulations in which a system, represented by an arrangement of connected sites, evolves over time according to an update rule which determines the future state of a site by considering its current state and the state of each of its neighbors. For example, in the classic "Game of Life" cellular automaton [@gardner_mathematical_1970], sites in a 2D square grid switch between "dead" and "alive" during each timestep based on the number of living neighbors surrounding them. In lattice Monte Carlo simulations for vacancy diffusion in crystalline solid materials, atoms move between neighboring sites at rates partially determined by the occupancy of their neighbors [@haley_vacancy_2006].
 
 These simulation classes have been implemented many times in various programming languages for a range of applications [@andersen_practical_2019; @raabe_cellular_2002]. However, these implementations typically focus on tuning an existing simulation form within a relatively narrow range of focus. For instance, `CellPyLib` [@antunes_cellpylib_2023], `netomaton` [@antunes_netomaton_2019], and `cellular_automaton` [@feistenauer_cellular_automaton_2021] are all libraries for simulating cellular automata, but they each are limited in the simulation geometry, the data type for the simulation state, the geometry of the neighborhood, or the strategy for applying the update rule. Similarly, `lattice_mc` [@Morgan2017] is an excellent Monte Carlo program that focuses solely on diffusion in ionic solids. While `KMCLib` [@leetmaa_kmclib_2014] is a more generic alternative, it is still (appropriately) limited in the form of the state and the update rule.
 
 The goal of `pylattica` is to synthesize the essential elements of these valuable simulation classes into a flexible and user-friendly framework for developing lattice models that do not fit neatly into the target use case of one of the existing packages. It accomplishes this by providing implementations of common lattice model features (e.g. various neighborhoods, methods for applying evolution rules, simulation structures, and analysis tools) while remaining unopinionated with regard to the ways these pieces are used in new models. It is implemented in python to maximize accessibility and interoperability with other scientific software tools, in particular, `pymatgen`, a package containing utilities for analysis in materials science [@ong_python_2013].
 
-Because `pylattica` is particularly focused on enabling fast iteration on simulation features during development, it prioritizes flexibility and application agnosticism over performance. Therefore, it is most appropriately used in cases when the developer needs to prototype and experiment with various forms of their model, or in cases when performance is not of the utmost importance.
+Because `pylattica` is focused on enabling fast iteration on simulation features during development, it prioritizes flexibility and application agnosticism over performance. Therefore, it is better suited for cases in which the developer needs to prototype and experiment with various forms of their simulation as opposed to honing in a hardened production model.
 
 # Package Overview
 
@@ -53,15 +53,13 @@ Of these three entities, only a `SimulationState` is required to run a simulatio
 
 ## Constructing Neighborhoods
 
-`pylattica` supports two and three dimensional square grid simulation structures out of the box (though any simulation structure can be created), and provides convenience methods for building them. Additionally, it provides a number of `NeighborhoodBuilder` classes which encode methods for specifying site neighbors in `Structure`s. Support for the following neighborhood types is provided:
+`pylattica` supports two and three dimensional square grid simulation structures out of the box (though any simulation structure can be created), and provides convenience methods for building them. Additionally, it provides a number of `NeighborhoodBuilder` classes which encode methods for specifying site neighbors in `Structure`s. The two most flexible `NeighborhoodBuilder` classes are the `DistanceNeighborhoodBuilder` and the `MotifNeighborhoodBuilder`. Using the `DistanceNeighborhoodBuilder`, the neighbors of a site are defined as all other sites falling within a particular cutoff distance. Using the `MotifNeighborhoodBuilder`, the locations of a site's neighbors are specified by providing a list of offset vectors from that site (one for each neighbor). While these two classes can be used to construct practically any neighborhood, builder classes for the following common neighborhoods are also provided:
 
 - Moore (square grid) [@packard_two-dimensional_1985]
 - Von Neumann (square grid) [@packard_two-dimensional_1985]
 - Pseudopentagonal (square grid) [@sieradzki_perceptive_2013]
 - Pseudohexagonal (square grid) [@sieradzki_perceptive_2013]
-- Circular (arbitrary structure)
 - Annular (arbitrary structure)
-- Motif-based (arbitrary structure)
 
 ## Simulation Execution
 
@@ -79,13 +77,13 @@ The result of a simulation run is an instance of `SimulationResult`, which store
 
 ![\label{fig_2} Example visualizations of two and three dimensional square grid simulation states.](./vizeg.png)
 
-`pylattica` provides basic utilities for analyzing the state of the simulation. These tools provide functionality for filtering and counting sites in a SimulationStep by arbitrary criteria (implemented as a function of the site’s state). Further specialized support is provided for simulation states in which the state of each site is a single discrete label (as is the case in traditional cellular automata).
+`pylattica` provides basic utilities for analyzing the state of the simulation. These tools provide functionality for filtering and counting sites in a `SimulationState` by arbitrary criteria (implemented as a function of the site’s state). Further specialized support is provided for simulation states in which the state of each site is a single discrete label (as is the case in traditional cellular automata).
 
 In the case of simulations with two- and three-dimensional square grid structures, `pylattica` provides visualization tools which convert `SimulationState`s into PNG images (as shown in \autoref{fig_2}) and `SimulationResult`s into animated GIFs.
 
 ## Crystal Structure Support and pymatgen
 
-`pylattica` was developed with simulations of crystalline materials in mind. As a result, it supports simulation `Structure`s defined with periodic boundaries and lattices with arbitrarily shaped unit cells. In service of developing simulations of real crystalline materials, it provides utility functions for defining neighborhoods in periodic space based on displacement motifs (e.g. octahedral or tetrahedral neighbors) and supports converting `pymatgen.Structure` objects to `pylattica` `Structure`s. This feature is intended to enable more seamless integration with existing materials science workflows.
+`pylattica` was developed with simulations of crystalline materials in mind. As a result, it supports simulation `Structure`s defined with periodic boundaries and lattices with arbitrarily shaped unit cells. These `Structure`s are supported by a `Lattice` class which was cloned from `pymatgen` and then adapted to the needs of `pylattica`, primarily because `pymatgen`'s implementation is hard-coded to use 3-dimensions, while `pylattica` strives for generality and enforces no such constraint. In service of developing simulations of real crystalline materials, `pylattica` also provides utility functions for defining neighborhoods in periodic space based on displacement motifs (e.g. octahedral or tetrahedral neighbors) and supports converting `pymatgen.Structure` objects to `pylattica` `Structure`s. This feature is intended to enable more seamless integration with existing materials science workflows.
 
 # Acknowledgments
 

pyproject.toml

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["setuptools>=42", "wheel", "setuptools-git-versioning"]
+requires = ["setuptools>=61", "wheel", "setuptools-git-versioning"]
 build-backend = "setuptools.build_meta"
 
 [project]
@@ -15,7 +15,7 @@ keywords = [
     "materials",
 ]
 
-license = { text = "modified BSD" }
+license = { text = "MIT" }
 authors = [{ name = "Max Gallant", email = "[email protected]" }]
 dynamic = ["version"]
 classifiers = [

src/pylattica/core/lattice.py

@@ -60,7 +60,7 @@ def pbc_diff_frac_vec(fcoords1: ArrayLike, fcoords2: ArrayLike, periodic):
 
 def pbc_diff_cart(cart_coords1: ArrayLike, cart_coords2: ArrayLike, lattice: Lattice):
     """Returns the Cartesian distance between two coordinates taking into
-    account periodic boundary conditions. (from pymatgen)
+    account periodic boundary conditions.
 
     Parameters
     ----------

src/pylattica/core/neighborhood_builders.py

@@ -143,7 +143,7 @@ class AnnularNeighborhoodBuilder(NeighborhoodBuilder):
     """
 
     def __init__(self, inner_radius: float, outer_radius: float):
-        """Instantiates a DistanceNeighborhoodBuilder
+        """Instantiates an AnnularNeighborhoodBuilder
 
         Parameters
         ----------
@@ -194,6 +194,7 @@ class MotifNeighborhoodBuilder(NeighborhoodBuilder):
     by one unit in each of the positive and negative y directions, then the spec
     parameter for this arrangement would look as follows.
 
+    ```
     {
         "A": [
             [0, 1],
@@ -206,6 +207,7 @@ class MotifNeighborhoodBuilder(NeighborhoodBuilder):
             [0, -1],
         ]
     }
+    ```
 
     Note that there is reciprocity here between the A and B sites. The A sites
     list B sites as their neighbors, and the B sites list A sites as their neighbors.