coxeter.families package¶

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 basic interface is defined by the ShapeFamily, which is a functor that is called to generate a shape. The 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 reproducing the exact set of shapes from publications.

Data:

DOI_SHAPE_REPOSITORIES

A mapping of DOIs to a list of shape families.

Classes:

`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].
`PlatonicFamily`()	The family of Platonic solids.
`RegularNGonFamily`()	The family of convex regular polygons.
`ShapeFamily`()	A factory for instances of `Shape`.
`TabulatedShapeFamily`()	A shape family corresponding to a tabulated set of shapes.
`TabulatedGSDShapeFamily`()	A tabulated shape family defined by a GSD shape schema.
`TruncatedTetrahedronFamily`()	The truncated tetrahedron family used in [DEG12].

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: [DEG12]
10.1103/PhysRevX.4.011024: [CKE+14]
10.1021/nn204012y: [DEG12]

class coxeter.families.Family323Plus¶

Bases: coxeter.families.plane_shape_families.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: coxeter.families.plane_shape_families.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: coxeter.families.plane_shape_families.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.PlatonicFamily¶

Bases: coxeter.families.tabulated_shape_family.TabulatedGSDShapeFamily

The family of Platonic solids.

The following parameters are required by this class:

name: The name of the Platonic solid. Options are “Cube”, “Dodecahedron”, “Icosahedron”, “Octahedron”, and “Tetrahedron”.

Methods:

`from_json_file`(filename, args, *kwargs)	Generate a subclass for a dataset from a JSON file.
`from_mapping`(mapping[, classname, docstring])	Generate a subclass for a dataset from a mapping.
`get_shape`(name)	Use the class’s data to produce a shape for the given name.

classmethod from_json_file(filename, *args, **kwargs)¶

Generate a subclass for a dataset from a JSON file.

This method simply loads the JSON file into a dictionary and calls from_mapping(), see that docstring for more information.

Parameters

filename (str) – A JSON file containing valid shape definitions.
*args – Passed on to from_mapping().
**kwargs – Passed on to from_mapping().

Returns

A subclass of this one associated with the the provided data.

classmethod from_mapping(mapping, classname=None, docstring=None)¶

Generate a subclass for a dataset from a mapping.

Notably, this method is a _class_ factory: rather than generating a new instance, this method actually generates a new subclass. This design is consistent with the usage ShapeFamily subclasses by direct interaction with the class (without instantiation).

Parameters

mapping (Mapping) – A dict-like object containing valid shape definitions.
classname (str, optional) – The name of the new class to use if provided (Default value: None).
docstring (str, optional) – The docstring to apply to the class.

Returns

A subclass of this one associated with the the provided data.

classmethod 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: The requested shape.
Return type: Shape

class coxeter.families.RegularNGonFamily¶

Bases: coxeter.families.shape_family.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 (greater than or equal to 3).
Returns: The corresponding regular polygon.
Return type: ConvexPolygon

classmethod make_vertices(n)¶

Generate vertices of a unit area n-gon.

Parameters: n (int) – An integer greater than or equal to 3.
Returns: The vertices of the polygon.
Return type: \((n, 3)\) numpy.ndarray of float

class coxeter.families.ShapeFamily¶

Bases: abc.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).

Methods:

get_shape()

Generate a shape.

abstract classmethod 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¶

Bases: coxeter.families.tabulated_shape_family.TabulatedShapeFamily

A tabulated shape family defined by a GSD shape schema.

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: filename_or_dict (str or Mapping) – A dictionary containing valid shape definitions or a JSON file that can be read into such a dictionary.

Methods:

`from_json_file`(filename, args, *kwargs)	Generate a subclass for a dataset from a JSON file.
`from_mapping`(mapping[, classname, docstring])	Generate a subclass for a dataset from a mapping.
`get_shape`(name)	Use the class’s data to produce a shape for the given name.

classmethod from_json_file(filename, *args, **kwargs)¶

Generate a subclass for a dataset from a JSON file.

This method simply loads the JSON file into a dictionary and calls from_mapping(), see that docstring for more information.

Parameters

filename (str) – A JSON file containing valid shape definitions.
*args – Passed on to from_mapping().
**kwargs – Passed on to from_mapping().

Returns

A subclass of this one associated with the the provided data.

classmethod from_mapping(mapping, classname=None, docstring=None)¶

Generate a subclass for a dataset from a mapping.

Notably, this method is a _class_ factory: rather than generating a new instance, this method actually generates a new subclass. This design is consistent with the usage ShapeFamily subclasses by direct interaction with the class (without instantiation).

Parameters

mapping (Mapping) – A dict-like object containing valid shape definitions.
classname (str, optional) – The name of the new class to use if provided (Default value: None).
docstring (str, optional) – The docstring to apply to the class.

Returns

A subclass of this one associated with the the provided data.

classmethod 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: The requested shape.
Return type: Shape

class coxeter.families.TabulatedShapeFamily¶

Bases: coxeter.families.shape_family.ShapeFamily

A shape family corresponding to a tabulated set of shapes.

Data can either be read from a file or provided in the form of a dictionary. If a filename is provided, it must be a JSON file that can be parsed into an appropriately formatted dictionary, namely a set of key-value pairs such that the call operator of this class can generate a Shape from the dictionary. The raw parsed JSON is accessible via the data attribute. Subclasses of this class implement the call operator to define exactly how the dictionary values are converted to a shape definition.

Methods:

`from_json_file`(filename, args, *kwargs)	Generate a subclass for a dataset from a JSON file.
`from_mapping`(mapping[, classname, docstring])	Generate a subclass for a dataset from a mapping.
`get_shape`()	Generate a shape.

classmethod from_json_file(filename, *args, **kwargs)¶

Generate a subclass for a dataset from a JSON file.

This method simply loads the JSON file into a dictionary and calls from_mapping(), see that docstring for more information.

Parameters

filename (str) – A JSON file containing valid shape definitions.
*args – Passed on to from_mapping().
**kwargs – Passed on to from_mapping().

Returns

A subclass of this one associated with the the provided data.

classmethod from_mapping(mapping, classname=None, docstring=None)¶

Generate a subclass for a dataset from a mapping.

Notably, this method is a _class_ factory: rather than generating a new instance, this method actually generates a new subclass. This design is consistent with the usage ShapeFamily subclasses by direct interaction with the class (without instantiation).

Parameters

mapping (Mapping) – A dict-like object containing valid shape definitions.
classname (str, optional) – The name of the new class to use if provided (Default value: None).
docstring (str, optional) – The docstring to apply to the class.

Returns

A subclass of this one associated with the the provided data.

abstract classmethod 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.TruncatedTetrahedronFamily¶

Bases: coxeter.families.plane_shape_families.Family323Plus

The truncated tetrahedron family used in [DEG12].

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