Families Module¶

Overview

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 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. Interactive models for these shapes can be found in the following tables:

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
    ...

Classes:

`CanonicalTrapezohedronFamily`()	The infinite family of canonical n-trapezohedra (antiprism duals).
`Family323Plus`()	The 323+ shape family defined in [CKE+14].
`Family423`()	The 423 shape family defined in [CKE+14].
`Family523`()	The 523 shape family defined in [CKE+14].
`RegularNGonFamily`()	The family of convex regular polygons.
`ShapeFamily`()	A factory for instances of `Shape`.
`TabulatedGSDShapeFamily`(data)	A tabulated shape family, used to generate families of named polyhedra.
`TetragonalDisphenoidFamily`()	The infinite family of tetragonal disphenoids (irregular tetrahedra).
`TruncatedTetrahedronFamily`()	The truncated tetrahedron family used in [DEG12a].
`UniformAntiprismFamily`()	The infinite family of uniform right antiprisms with unit volume.
`UniformDipyramidFamily`()	The family of uniform right dipyramids with unit volume.
`UniformPrismFamily`()	The infinite family of uniform right prisms with unit volume.
`UniformPyramidFamily`()	The family of uniform right pyramids with unit volume.

Data:

DOI_SHAPE_REPOSITORIES

A mapping of DOIs to a list of shape families.

class coxeter.families.CanonicalTrapezohedronFamily¶

Bases: ShapeFamily

The infinite family of canonical n-trapezohedra (antiprism duals).

Formulas for vertices are derived from [Raj15] rather than via explicit canonicalization to ensure the method is deterministic and fast.

Methods:

`get_shape`(n)	Generate a canonical n-antiprism of unit volume.
`make_vertices`(n)	Generate the vertices of a uniform right n-antiprism with unit volume.

classmethod get_shape(n: int)¶

Generate a canonical n-antiprism of unit volume.

Parameters:: n (int) – The number of vertices of the base polygons (\(n \geq 3\)).
Return type:: ConvexPolyhedron

classmethod make_vertices(n)¶

Generate the vertices of a uniform right n-antiprism with unit volume.

Parameters:: n (int) – The number of vertices of the base polygons (\(n \geq 3\)).
Returns:: The vertices of the trapezohedron.
Return type:: \((n*2 + 2, 3)\) numpy.ndarray of float

coxeter.families.DOI_SHAPE_REPOSITORIES = {}¶

A mapping of DOIs to a list of shape families.

Each known DOI is associated with a list of shape families that can be used to generate the shapes from those papers. Currently supported DOIs are:

10.1126/science.1220869: [DEG12b]
10.1103/PhysRevX.4.011024: [CKE+14]
10.1021/nn204012y: [DEG12a]

class coxeter.families.Family323Plus¶

Bases: TruncationPlaneShapeFamily

The 323+ shape family defined in [CKE+14].

This class requires the parameters

\(a \in [1, 3]\)

\(c \in [1, 3]\)

The \(b\) parameter is always equal to 1 for this family.

The extremal shapes in this shape family are an octahedron at (1, 1), a tetrahedron at (3, 1) and (1, 3), and a cube at (3, 3).

Methods:

`get_plane_types`()	Get the types of the planes.
`get_planes`()	Get the set of planes used to truncate the shape.
`get_shape`(a, c)	Generate a shape for the provided parameters.
`make_vertices`(a, b, c)	Generate vertices from the a, b, and c parameters.

classmethod get_plane_types()¶

Get the types of the planes.

The types are encoded via the following integer mapping:

type 0 corresponds to the parameter a.
type 1 corresponds to the parameter b.
type 2 corresponds to the parameter c.

Returns:: The plane types.
Return type:: (\(N_{planes}\), ) numpy.ndarray of int

classmethod get_planes()¶

Get the set of planes used to truncate the shape.

Returns:: The planes defining this family
Return type:: (\(N_{planes}\), 3) numpy.ndarray of float

classmethod get_shape(a, c)¶

Generate a shape for the provided parameters.

Parameters:

a (float) – The parameter \(a \in [1, 3]\).
c (float) – The parameter \(c \in [1, 3]\).

Returns:

The desired shape.

Return type:

ConvexPolyhedron

classmethod make_vertices(a, b, c)¶

Generate vertices from the a, b, and c parameters.

Parameters:

a (float) – The a parameter.
b (float) – The b parameter.
c (float) – The c parameter.

Returns:

The vertices of the shape generated by the provided parameters.

Return type:

(\(N_{vertices}\), 3) numpy.ndarray of float

class coxeter.families.Family423¶

Bases: TruncationPlaneShapeFamily

The 423 shape family defined in [CKE+14].

This class requires the parameters

\(a \in [1, 2]\)

\(c \in [2, 3]\)

The \(b\) parameter is always equal to 2 for this family.

The extremal shapes in this shape family are a cuboctahedron at (1, 2), an octahedron at (2, 2), a cube at (1, 3), and a rhombic dodecahedron at (2, 3).

Methods:

`get_plane_types`()	Get the types of the planes.
`get_planes`()	Get the set of planes used to truncate the shape.
`get_shape`(a, c)	Generate a shape for the provided parameters.
`make_vertices`(a, b, c)	Generate vertices from the a, b, and c parameters.

classmethod get_plane_types()¶

Get the types of the planes.

The types are encoded via the following integer mapping:

type 0 corresponds to the parameter a.
type 1 corresponds to the parameter b.
type 2 corresponds to the parameter c.

Returns:: The plane types.
Return type:: (\(N_{planes}\), ) numpy.ndarray of int

classmethod get_planes()¶

Get the set of planes used to truncate the shape.

Returns:: The planes defining this family
Return type:: (\(N_{planes}\), 3) numpy.ndarray of float

classmethod get_shape(a, c)¶

Generate a shape for the provided parameters.

Parameters:

a (float) – The parameter \(a \in [1, 2]\).
c (float) – The parameter \(c \in [2, 3]\).

Returns:

The desired shape.

Return type:

ConvexPolyhedron

classmethod make_vertices(a, b, c)¶

Generate vertices from the a, b, and c parameters.

Parameters:

a (float) – The a parameter.
b (float) – The b parameter.
c (float) – The c parameter.

Returns:

The vertices of the shape generated by the provided parameters.

Return type:

(\(N_{vertices}\), 3) numpy.ndarray of float

class coxeter.families.Family523¶

Bases: TruncationPlaneShapeFamily

The 523 shape family defined in [CKE+14].

This class requires the parameters

\(a \in [1, s\sqrt{5}]\)

\(c \in [S^2, 3]\)

where \(S = \frac{1}{2}\left(\sqrt{5} + 1\right)\) is the golden ratio and \(s = \frac{1}{2}\left(\sqrt{5} - 1\right)\) is its inverse. The \(b\) parameter is always equal to 2 for this family.

The extremal shapes in this shape family are an icosidodecahedron at (\(1\), \(S^2\)), an icosahedron at (\(s\sqrt{5}\), \(S^2\)), a dodecahedron at (\(1\), \(3\)), and a rhombic triacontahedron at (\(s\sqrt{5}\), \(3\)).

Attributes:

`S`	The constant S (the golden ratio).
`s`	The constant s (the inverse of the golden ratio).

Methods:

`get_plane_types`()	Get the types of the planes.
`get_planes`()	Get the set of planes used to truncate the shape.
`get_shape`(a, c)	Generate a shape for the provided parameters.
`make_vertices`(a, b, c)	Generate vertices from the a, b, and c parameters.

S = 1.618033988749895¶: The constant S (the golden ratio).

classmethod get_plane_types()¶

Get the types of the planes.

The types are encoded via the following integer mapping:

type 0 corresponds to the parameter a.
type 1 corresponds to the parameter b.
type 2 corresponds to the parameter c.

Returns:: The plane types.
Return type:: (\(N_{planes}\), ) numpy.ndarray of int

classmethod get_planes()¶

Get the set of planes used to truncate the shape.

Returns:: The planes defining this family
Return type:: (\(N_{planes}\), 3) numpy.ndarray of float

classmethod get_shape(a, c)¶

Generate a shape for the provided parameters.

Parameters:

a (float) – The parameter \(a \in [1, s\sqrt{5}]\).
c (float) – The parameter \(c \in [S^2, 3]\).

Returns:

The desired shape.

Return type:

ConvexPolyhedron

classmethod make_vertices(a, b, c)¶

Generate vertices from the a, b, and c parameters.

Parameters:

a (float) – The a parameter.
b (float) – The b parameter.
c (float) – The c parameter.

Returns:

The vertices of the shape generated by the provided parameters.

Return type:

(\(N_{vertices}\), 3) numpy.ndarray of float

s = 0.6180339887498948¶: The constant s (the inverse of the golden ratio).

class coxeter.families.RegularNGonFamily¶

Bases: ShapeFamily

The family of convex regular polygons.

This class generates the set of convex regular polygons with \(n\) sides. The polygons are normalized to be unit area by default, and the initial vertex always lies on the \(x\) axis (so, for example, a 4-sided shape generated by this will look like a diamond, i.e. a square rotated by 45 degrees).

The following parameters are required by this class:

\(n\): The number of vertices of the polygon

Methods:

`get_shape`(n)	Generate a unit area n-gon.
`make_vertices`(n)	Generate vertices of a unit area n-gon.

classmethod get_shape(n)¶

Generate a unit area n-gon.

Parameters:: n (int) – The number of vertices (\(n \geq 3\)).
Return type:: ConvexPolygon

classmethod make_vertices(n)¶

Generate vertices of a unit area n-gon.

Parameters:: n (int) – The number of vertices of the polygon (\(n \geq 3\)).
Returns:: :math:`(n, 3)` :class:`numpy.ndarray` of float
Return type:: The vertices of the polygon.

class coxeter.families.ShapeFamily¶

Bases: ABC

A factory for instances of Shape.

This abstract class represents a simple promise of a get_shape method that accepts some set of arguments and returns some shape class. The precise behavior is left up to specific subclasses, which document the parameters in the class docstring.

This class is designed to never be instantiated. All relevant operations of its subclasses should be classmethods, and any data intrinsic to a family should be stored within the class. This design avoids creating an antipattern of instantiating a stateless class, while also providing a suitable means for using inheritance to create meaningful relationships between shape families. It also simplifies user APIs, avoiding confusing idioms like shape = family()(SHAPE_NAME). For instance, given a family for generating regular polygons, getting a hexagon should look roughly like family.get_shape(n=6).

Attributes:

get_shape

Generate a shape.

abstract property get_shape¶

Generate a shape.

Subclasses must define this function to accept whatever parameters are necessary to define a shape. The method should return an instance of some concrete subclass of Shape.

class coxeter.families.TabulatedGSDShapeFamily(data)¶

Bases: ShapeFamily

A tabulated shape family, used to generate families of named polyhedra.

The values of the dictionary used to construct this class must adhere to the GSD shape spec. Each mapping may contain additional data, which is ignored when the class is called to actually produce Shape objects.

Parameters:: data (Mapping) – A dictionary containing valid shape definitions.

Methods:

get_shape(name)

Use the class's data to produce a shape for the given name.

Attributes:

names

A list of names for the shapes in the family, in alphabetical order.

get_shape(name)¶

Use the class’s data to produce a shape for the given name.

Parameters:: name (str) – The key of the desired shape in the data dict.
Returns:: :class:`~.ConvexPolyhedron`
Return type:: The requested shape.

property names¶: A list of names for the shapes in the family, in alphabetical order.

class coxeter.families.TetragonalDisphenoidFamily¶

Bases: ShapeFamily

The infinite family of tetragonal disphenoids (irregular tetrahedra).

A disphenoid is a special case of an (irregular) tetrahedron which can be inscribed in a cuboid. The special case of \(a=b=c\) yields the Platonic tetrahedron, which has \(T_d\) symmetry. All other cases yield tetragonal disphenoids with \(D_{2h}\) symmetry. For the space-filling disphenoid capable of forming the disphenoid tetrahedral honeycomb, set \(a=b=1\) and \(c=sqrt(2)\).

Methods:

`get_shape`(a, b, c)	Generate a disphenoid inscribed in a cuboid with edges a,b,c.
`make_vertices`(a, b, c)	Make the vertices of a disphenoid inscribed in a cuboid with edges a,b,c.

classmethod get_shape(a, b, c)¶

Generate a disphenoid inscribed in a cuboid with edges a,b,c.

Parameters:

a (float) – The extent of the inscribing cuboid along the \(x\) axis.
b (float) – The extent of the inscribing cuboid along the \(y\) axis.
c (float) – The extent of the inscribing cuboid along the \(z\) axis.

Return type:

ConvexPolyhedron

classmethod make_vertices(a, b, c)¶: Make the vertices of a disphenoid inscribed in a cuboid with edges a,b,c.

class coxeter.families.TruncatedTetrahedronFamily¶

Bases: Family323Plus

The truncated tetrahedron family used in [DEG12a].

The following parameters are required by this class:

truncation \(\in [0, 1]\)

This family is constructed as a limiting case of Family323Plus with a = 1. The c value is then directly related to a linear interpolation over truncations. In particular, \(c = 3 - 2(\text{truncation})\).

Methods:

`get_plane_types`()	Get the types of the planes.
`get_planes`()	Get the set of planes used to truncate the shape.
`get_shape`(truncation)	Generate a shape for a given truncation value.
`make_vertices`(a, b, c)	Generate vertices from the a, b, and c parameters.

classmethod get_plane_types()¶

Get the types of the planes.

The types are encoded via the following integer mapping:

type 0 corresponds to the parameter a.
type 1 corresponds to the parameter b.
type 2 corresponds to the parameter c.

Returns:: The plane types.
Return type:: (\(N_{planes}\), ) numpy.ndarray of int

classmethod get_planes()¶

Get the set of planes used to truncate the shape.

Returns:: The planes defining this family
Return type:: (\(N_{planes}\), 3) numpy.ndarray of float

classmethod get_shape(truncation)¶

Generate a shape for a given truncation value.

Parameters:: truncation (float) – The parameter \(truncation \in [0, 1]\).
Returns:: The desired truncated tetrahedron.
Return type:: ConvexPolyhedron

classmethod make_vertices(a, b, c)¶

Generate vertices from the a, b, and c parameters.

Parameters:

a (float) – The a parameter.
b (float) – The b parameter.
c (float) – The c parameter.

Returns:

The vertices of the shape generated by the provided parameters.

Return type:

(\(N_{vertices}\), 3) numpy.ndarray of float

class coxeter.families.UniformAntiprismFamily¶

Bases: ShapeFamily

The infinite family of uniform right antiprisms with unit volume.

As with the RegularNGonFamily, the initial vertex lies on the \(x\) axis. The bottom face of each antiprism is rotated \(\pi/n\) radians relative to the top face.

Methods:

`get_shape`(n)	Generate a uniform right n-antiprism of unit volume.
`make_vertices`(n)	Generate the vertices of a uniform right n-antiprism with unit volume.

classmethod get_shape(n)¶

Generate a uniform right n-antiprism of unit volume.

Parameters:: n (int) – The number of vertices of the base polygons (\(n \geq 3\)).
Return type:: ConvexPolyhedron

classmethod make_vertices(n)¶

Generate the vertices of a uniform right n-antiprism with unit volume.

Parameters:: n (int) – The number of vertices of the base polygons (\(n \geq 3\)).
Returns:: The vertices of the antiprism.
Return type:: \((n*2, 3)\) numpy.ndarray of float

class coxeter.families.UniformDipyramidFamily¶

Bases: ShapeFamily

The family of uniform right dipyramids with unit volume.

As with the RegularNGonFamily, the initial vertex of the base polygon lies on the \(x\) axis.

Methods:

`get_shape`(n)	Generate a uniform right n-dipyramid of unit volume.
`make_vertices`(n)	Generate the vertices of a uniform right n-dipyramid with unit volume.

classmethod get_shape(n)¶

Generate a uniform right n-dipyramid of unit volume.

Parameters:: n (int) – The number of vertices of the base polygon (\(3 \leq n \leq 5\)).
Return type:: ConvexPolyhedron

classmethod make_vertices(n)¶

Generate the vertices of a uniform right n-dipyramid with unit volume.

Parameters:: n (int) – The number of vertices of the base polygon (\(3 \leq n \leq 5\)).
Returns:: The vertices of the dipyramid.
Return type:: \((n+2, 3)\) numpy.ndarray of float

class coxeter.families.UniformPrismFamily¶

Bases: ShapeFamily

The infinite family of uniform right prisms with unit volume.

As with the RegularNGonFamily, the initial vertex lies on the \(x\) axis.

Methods:

`get_shape`(n)	Generate a uniform right n-prism of unit volume.
`make_vertices`(n)	Generate the vertices of a uniform right n-prism with unit volume.

classmethod get_shape(n)¶

Generate a uniform right n-prism of unit volume.

Parameters:: n (int) – The number of vertices of the base polygons (\(n \geq 3\)).
Return type:: ConvexPolyhedron

classmethod make_vertices(n)¶

Generate the vertices of a uniform right n-prism with unit volume.

Parameters:: n (int) – The number of vertices of the base polygons (\(n \geq 3\)).
Returns:: The vertices of the prism.
Return type:: \((n*2, 3)\) numpy.ndarray of float

class coxeter.families.UniformPyramidFamily¶

Bases: ShapeFamily

The family of uniform right pyramids with unit volume.

As with the RegularNGonFamily, the initial vertex of the base polygon lies on the \(x\) axis.

Methods:

`get_shape`(n)	Generate a uniform right n-pyramid of unit volume.
`make_vertices`(n)	Generate the vertices of a uniform right n-pyramid with unit volume.

classmethod get_shape(n)¶

Generate a uniform right n-pyramid of unit volume.

Parameters:: n (int) – The number of vertices of the base polygon (\(3 \leq n \leq 5\)).
Return type:: ConvexPolyhedron

classmethod make_vertices(n)¶

Generate the vertices of a uniform right n-pyramid with unit volume.

Parameters:: n (int) – The number of vertices of the base polygon (\(3 \leq n \leq 5\)).
Returns:: The vertices of the pyramid.
Return type:: \((n+1, 3)\) numpy.ndarray of float

class coxeter.families.PlatonicFamily¶

Bases:

The family of Platonic solids (5 total).

Options can be found in the Platonic Solids Table.

Methods:

`__iter__`()	Iterate over the names and geometries associated with the class.
`get_shape`(name)	Use the class's data to produce a shape for the given name.

__iter__()¶

Iterate over the names and geometries associated with the class.

Yields:: tuple[str, ConvexPolyhedron] – An iterator of shape names and the related polyhedron objects.

get_shape(name)¶

Use the class’s data to produce a shape for the given name.

Parameters:: name (str) – The key of the desired shape in the data dict.
Returns:: :class:`~.ConvexPolyhedron`
Return type:: The requested shape.

class coxeter.families.ArchimedeanFamily¶

Bases:

The family of Archimedean solids (13 total).

Options can be found in the Archimedean Solids Table.

Methods:

`__iter__`()	Iterate over the names and geometries associated with the class.
`get_shape`(name)	Use the class's data to produce a shape for the given name.

__iter__()¶

Iterate over the names and geometries associated with the class.

Yields:: tuple[str, ConvexPolyhedron] – An iterator of shape names and the related polyhedron objects.

get_shape(name)¶

Use the class’s data to produce a shape for the given name.

Parameters:: name (str) – The key of the desired shape in the data dict.
Returns:: :class:`~.ConvexPolyhedron`
Return type:: The requested shape.

class coxeter.families.CatalanFamily¶

Bases:

The family of Catalan solids, also known as Archimedean duals (13 total).

Options can be found in the Catalan Solids Table.

Methods:

`__iter__`()	Iterate over the names and geometries associated with the class.
`get_shape`(name)	Use the class's data to produce a shape for the given name.

__iter__()¶

Iterate over the names and geometries associated with the class.

Yields:: tuple[str, ConvexPolyhedron] – An iterator of shape names and the related polyhedron objects.

get_shape(name)¶

Use the class’s data to produce a shape for the given name.

Parameters:: name (str) – The key of the desired shape in the data dict.
Returns:: :class:`~.ConvexPolyhedron`
Return type:: The requested shape.

class coxeter.families.JohnsonFamily¶

Bases:

The family of Johnson solids, as enumerated in [Joh66] (92 total).

Options can be found in the Johnson Solids Table.

Methods:

`__iter__`()	Iterate over the names and geometries associated with the class.
`get_shape`(name)	Use the class's data to produce a shape for the given name.

__iter__()¶

Iterate over the names and geometries associated with the class.

Yields:: tuple[str, ConvexPolyhedron] – An iterator of shape names and the related polyhedron objects.

get_shape(name)¶

Use the class’s data to produce a shape for the given name.

Parameters:: name (str) – The key of the desired shape in the data dict.
Returns:: :class:`~.ConvexPolyhedron`
Return type:: The requested shape.