Merge branch 'master' into Feature/Additional-geometry-file-export-me…

…thods

.github/workflows/CI.yaml

@@ -31,7 +31,7 @@ jobs:
       with:
         python-version: ${{ matrix.python-version }}
     - name: Set up Python environment
-      uses: glotzerlab/workflows/setup-uv@3573ddaebf3290e00bfb150b82a46412192a61d3
+      uses: glotzerlab/workflows/setup-uv@33f1cd458d4d39d0101cfa67d13dd3a9e118eefd
       with:
         only-binary: ":none:"
         lockfile: ".github/requirements${{matrix.python-version}}.txt"

.github/workflows/PublishPyPI.yaml

@@ -25,11 +25,11 @@ jobs:
         python -m pip install --progress-bar off build
     - name: Build wheels and sdist
       run: python -m build --sdist --wheel --outdir dist/ .
-    - uses: actions/upload-artifact@v4.3.3
+    - uses: actions/upload-artifact@v4.4.0
       with:
         name: wheel
         path: dist/*.whl
-    - uses: actions/upload-artifact@v4.3.3
+    - uses: actions/upload-artifact@v4.4.0
       with:
         name: sdist
         path: dist/*.tar.gz
@@ -41,17 +41,17 @@ jobs:
     if: startsWith(github.ref, 'refs/tags/v')
     steps:
     - name: Download artifact sdist
-      uses: actions/[email protected].7
+      uses: actions/[email protected].8
       with:
         name: sdist
         path: dist
     - name: Download artifact wheel
-      uses: actions/[email protected].7
+      uses: actions/[email protected].8
       with:
         name: wheel
         path: dist
     - name: Publish to PyPI
-      uses: pypa/gh-action-pypi-publish@v1.9.0
+      uses: pypa/gh-action-pypi-publish@v1.10.0
       with:
         user: __token__
         password: ${{ secrets.PYPI_API_TOKEN }}

.github/workflows/update_pipfiles.yaml

@@ -16,7 +16,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
-    - uses: glotzerlab/workflows/setup-uv@1fcb2b253bf794b4e47cdff43479b145633f99e1
+    - uses: glotzerlab/workflows/setup-uv@33f1cd458d4d39d0101cfa67d13dd3a9e118eefd
     - name: Set up Python environment
       run: |
         for v in "3.8" "3.9" "3.10" "3.11" "3.12"; do

ChangeLog.rst

@@ -4,6 +4,29 @@ This project adheres to `Semantic Versioning <http://semver.org/spec/v2.0.0.html
 v0.x.x - 20xx-xx-xx
 -------------------
 
+Breaking
+~~~~~
+
+- [breaking] The hidden ``TabulatedShapeFamily`` class has been removed, with functionality moved to ``TabulatedGSDShapeFamily``.
+
+Added
+~~~~~
+
+- ``TabulatedGSDShapeFamilies`` are now iterable, allowing easier access to shapes.
+- New ``UniformPrismFamily``, ``UniformAntiprismFamily``, ``UniformPyramidFamily``, and ``UniformDipyramidFamily``
+- New documentation to assist users initialize common geometries.
+
+Changed
+~~~~~~~
+
+- The data in ``DOI_SHAPE_REPOSITORIES`` for source :cite:`Damasceno2012` is now sorted to match the order described in the paper.
+
+Deprecated
+~~~~~~~~~~
+
+- The ``PrismAntiprismFamily`` and ``PyramidDipyramidFamily`` have been deprecated in favor of the new families added above, which are faster, more consistent, and present a simplified interface.
+  The deprecated code was retained for backwards compatibility, but is no longer included in the documentation.
+
 v0.8.0 - 2024-02-21
 -------------------
 

coxeter/families/__init__.py

@@ -4,17 +4,66 @@
 """Provide tools for generating shapes.
 
 Shape families are coxeter's way of providing well-defined methods for
-generating classes of shapes according to some set of rules. The basic
-interface is defined by the :class:`~.ShapeFamily`, which is a functor that is
-called to generate a shape. The :class:`~.TabulatedShapeFamily` group of
-subclasses enable the generation of shape families according to some
-tabulated set of data, while other families are defined by some set of
-(discrete or continuous) parameters that are used to construct a shape
-analytically.
-
-The `DOI_SHAPE_REPOSITORIES` variable provides convenient access to the shape families
-associated with different scientific publications. This dataset is useful for
+generating classes of shapes according to some set of rules. The
+:class:`~.TabulatedGSDShapeFamily` group of subclasses enable the generation of shape
+families according to some tabulated set of data, while other families are defined by
+some set of parameters that are used to construct a shape analytically. Discrete
+families -- those that contain a fixed number of individual shapes -- may be iterated
+over.
+
+
+Example:
+
+    >>> from coxeter.families import PlatonicFamily
+    >>> for name, shape in PlatonicFamily:
+    >>>    print(name, shape.num_faces)
+    ... (Cube, 6)
+    ... (Dodecahedron, 12)
+    ... (Icosahedron, 20)
+    ... (Octahedron, 8)
+    ... (Tetrahedron, 4)
+
+    >>> cube = PlatonicFamily.get_shape("Cube")
+    >>> cube.num_faces
+    ... 6
+
+
+For continuous families of shapes, one must instead provide the required parameters.
+
+
+Example:
+
+    >>> from coxeter.families import Family423
+    >>> cube = Family423.get_shape(a=1.0, c=3.0) # These values yield a Platonic cube
+    >>> cube.num_faces
+    ... 6
+
+The `DOI_SHAPE_REPOSITORIES` variable provides convenient access to the shape family or
+families associated with different scientific publications. This dataset is useful for
 reproducing the exact set of shapes from publications.
+
+For convenience, shapes included in the paper *10.1126/science.1220869* may be accessed
+as a single family. These are indexed in a three character format consistent with the
+supplementary information of that publication.
+
+
+Example:
+
+    >>> from coxeter.families import DOI_SHAPE_REPOSITORIES
+    >>> DOI_SHAPE_REPOSITORIES["10.1103/PhysRevX.4.011024"]
+    ... [Family323Plus, Family423, Family523]
+
+    >>> science_family = DOI_SHAPE_REPOSITORIES["10.1126/science.1220869"][0]
+    >>> for code, shape in science_family:
+    >>>     print(code, shape.num_vertices)
+    ... (P01, 4)  # Tetrahedron
+    ... (P02, 8)  # Octahedron
+    ... (P03, 6)  # Cube
+    ... (P04, 20) # Icosahedron
+    ... (P05, 12) # Dodecahedron
+    ... (A01, 14) # Cuboctahedron
+    ... ...
+
 """
 
 from .common import (
@@ -25,6 +74,10 @@
     PrismAntiprismFamily,
     PyramidDipyramidFamily,
     RegularNGonFamily,
+    UniformAntiprismFamily,
+    UniformDipyramidFamily,
+    UniformPrismFamily,
+    UniformPyramidFamily,
 )
 from .doi_data_repositories import _doi_shape_collection_factory, _KeyedDefaultDict
 from .plane_shape_families import (
@@ -34,7 +87,7 @@
     TruncatedTetrahedronFamily,
 )
 from .shape_family import ShapeFamily
-from .tabulated_shape_family import TabulatedGSDShapeFamily, TabulatedShapeFamily
+from .tabulated_shape_family import TabulatedGSDShapeFamily
 
 # Note for devs: we want this object to be documented in the public API. The Sphinx
 # method for documenting a module-level constant is placing the docstring directly below
@@ -61,14 +114,17 @@
     "Family423",
     "Family523",
     "PlatonicFamily",
+    "UniformAntiprismFamily",
+    "UniformDipyramidFamily",
+    "UniformPrismFamily",
+    "UniformPyramidFamily",
     "ArchimedeanFamily",
     "CatalanFamily",
     "JohnsonFamily",
     "PrismAntiprismFamily",
     "PyramidDipyramidFamily",
     "RegularNGonFamily",
     "ShapeFamily",
-    "TabulatedShapeFamily",
     "TabulatedGSDShapeFamily",
     "TruncatedTetrahedronFamily",
 ]