From 4b2c252b95e12f191090595bd29f26d443c5add0 Mon Sep 17 00:00:00 2001 From: Max Gallant Date: Thu, 8 Feb 2024 13:39:47 -0800 Subject: [PATCH 1/8] Fix doc typos --- src/pylattica/core/neighborhood_builders.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/pylattica/core/neighborhood_builders.py b/src/pylattica/core/neighborhood_builders.py index 96eab88..961754f 100644 --- a/src/pylattica/core/neighborhood_builders.py +++ b/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. From c57bbec965b31a40cf157b4c9033e45cc2ae25a9 Mon Sep 17 00:00:00 2001 From: Max Gallant Date: Thu, 8 Feb 2024 14:36:23 -0800 Subject: [PATCH 2/8] Remove nonexistant changelog --- CHANGELOG.md | 0 mkdocs.yml | 1 - 2 files changed, 1 deletion(-) delete mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index e69de29..0000000 diff --git a/mkdocs.yml b/mkdocs.yml index f30aa6d..6638c50 100644 --- a/mkdocs.yml +++ b/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 From df911e27334f78487cec6c42f1b6b6112fafa25a Mon Sep 17 00:00:00 2001 From: Max Gallant Date: Thu, 8 Feb 2024 14:37:30 -0800 Subject: [PATCH 3/8] Add detail about neighborhood construction --- paper/paper.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/paper/paper.md b/paper/paper.md index ee72162..1e3c918 100644 --- a/paper/paper.md +++ b/paper/paper.md @@ -29,7 +29,7 @@ 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. @@ -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 From 65c679094acab48e487b0c56ac61be99b47f05a8 Mon Sep 17 00:00:00 2001 From: Max Gallant Date: Thu, 8 Feb 2024 14:37:46 -0800 Subject: [PATCH 4/8] Add detail about pymatgen lattice functionality --- paper/paper.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/paper/paper.md b/paper/paper.md index 1e3c918..9142679 100644 --- a/paper/paper.md +++ b/paper/paper.md @@ -77,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 structures are implemented using a `Lattice` class which uses functionality from `pymatgen` to convert coordinates between the basis of the lattice and the Cartesian basis. 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 From 491bd5ef70a245da4b88fd6b7f422e6790398411 Mon Sep 17 00:00:00 2001 From: Max Gallant Date: Thu, 8 Feb 2024 14:37:54 -0800 Subject: [PATCH 5/8] Remove misleading comment about source of code --- src/pylattica/core/lattice.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pylattica/core/lattice.py b/src/pylattica/core/lattice.py index 7e1f4fd..8d081c3 100644 --- a/src/pylattica/core/lattice.py +++ b/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 ---------- From 1af83d1c0506cf72f748948d5a08288f9686d2e8 Mon Sep 17 00:00:00 2001 From: Max Gallant Date: Fri, 9 Feb 2024 07:55:19 -0800 Subject: [PATCH 6/8] Small tweaks to license and installation --- LICENSE | 2 +- pyproject.toml | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/LICENSE b/LICENSE index f24d03e..9220509 100644 --- a/LICENSE +++ b/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 diff --git a/pyproject.toml b/pyproject.toml index 0f7154f..5d8b1cd 100644 --- a/pyproject.toml +++ b/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 = "maxg@lbl.gov" }] dynamic = ["version"] classifiers = [ From ed16a38a1f57623ee24a0cb68a8151d937389915 Mon Sep 17 00:00:00 2001 From: Max Gallant Date: Fri, 9 Feb 2024 08:17:02 -0800 Subject: [PATCH 7/8] Rephrase paper sentence about pymatgen lattices --- paper/paper.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/paper/paper.md b/paper/paper.md index 9142679..d6a6fa1 100644 --- a/paper/paper.md +++ b/paper/paper.md @@ -35,7 +35,7 @@ These simulation classes have been implemented many times in various programming 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 @@ -83,7 +83,7 @@ In the case of simulations with two- and three-dimensional square grid structure ## 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. These structures are implemented using a `Lattice` class which uses functionality from `pymatgen` to convert coordinates between the basis of the lattice and the Cartesian basis. 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. +`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 with functionality which was cloned from `pymatgen` and then adjusted 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 From ee988871cd0b7e600e783762ee24d5432c6e632e Mon Sep 17 00:00:00 2001 From: Max Gallant Date: Fri, 9 Feb 2024 08:21:48 -0800 Subject: [PATCH 8/8] better wording --- paper/paper.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/paper/paper.md b/paper/paper.md index d6a6fa1..52c0f26 100644 --- a/paper/paper.md +++ b/paper/paper.md @@ -83,7 +83,7 @@ In the case of simulations with two- and three-dimensional square grid structure ## 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. These `Structure`s are supported by a `Lattice` class with functionality which was cloned from `pymatgen` and then adjusted 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. +`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