Make tabulated shape families iterable (#234)

* Improve ngon family

* Add shapes classmethod to named tabulated families

* Update johnson family docstring

* Mostly working refactor

* Manually instantiate shape classes

* Fix iteration

* Remove dynamic generation oddness

* Remove unused parent class

* Fix docstring

* Fix doi_data families

* Fix tabulated families in preparation for autodoc

* Update docs

* Fix autodoc

* Fix common.py

* Update docstring for tabulated families

* Update science family data and add tests

* Update usage info for doi families

* Deprecate prism and antiprism families

* Update docs to show deprecation

* Rename to Uniform*Family

* Fix names in __init__

* Update docstrings and add tests

* Add pyramid and dipyramid families

* Fix docstrings

* Add pyramid dipyramid and tests

* Simplify dipyramid area formula

* Update changelog

* Update ChangeLog.rst

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",
 ]