def hom(self, A, B):
"""
Returns a 2-tuple of sets of morphisms between objects A and
B: one set of morphisms listed as premises, and the other set
of morphisms listed as conclusions.
Examples
========
>>> from sympy.categories import Object, NamedMorphism, Diagram
>>> from sympy import pretty
>>> A = Object("A")
>>> B = Object("B")
>>> C = Object("C")
>>> f = NamedMorphism(A, B, "f")
>>> g = NamedMorphism(B, C, "g")
>>> d = Diagram([f, g], {g * f: "unique"})
>>> print(pretty(d.hom(A, C), use_unicode=False))
({g*f:A-->C}, {g*f:A-->C})
See Also
========
Object, Morphism
"""
premises = EmptySet()
conclusions = EmptySet()
for morphism in self.premises.keys():
if (morphism.domain == A) and (morphism.codomain == B):
premises |= FiniteSet(morphism)
for morphism in self.conclusions.keys():
if (morphism.domain == A) and (morphism.codomain == B):
conclusions |= FiniteSet(morphism)
return (premises, conclusions)
def _get_connected_components(objects, merged_morphisms):
"""
Given a container of morphisms, returns a list of connected
components formed by these morphisms. A connected component
is represented by a diagram consisting of the corresponding
morphisms.
"""
component_index = {}
for o in objects:
component_index[o] = None
# Get the underlying undirected graph of the diagram.
adjlist = DiagramGrid._get_undirected_graph(objects, merged_morphisms)
def traverse_component(object, current_index):
"""
Does a depth-first search traversal of the component
containing ``object``.
"""
component_index[object] = current_index
for o in adjlist[object]:
if component_index[o] is None:
traverse_component(o, current_index)
# Traverse all components.
current_index = 0
for o in adjlist:
if component_index[o] is None:
traverse_component(o, current_index)
current_index += 1
# List the objects of the components.
component_objects = [[] for i in xrange(current_index)]
for o, idx in component_index.items():
component_objects[idx].append(o)
# Finally, list the morphisms belonging to each component.
#
# Note: If some objects are isolated, they will not get any
# morphisms at this stage, and since the layout algorithm
# relies, we are essentially going to lose this object.
# Therefore, check if there are isolated objects and, for each
# of them, provide the trivial identity morphism. It will get
# discarded later, but the object will be there.
component_morphisms = []
for component in component_objects:
current_morphisms = {}
for m in merged_morphisms:
if (m.domain in component) and (m.codomain in component):
current_morphisms[m] = merged_morphisms[m]
if len(component) == 1:
# Let's add an identity morphism, for the sake of
# surely having morphisms in this component.
current_morphisms[IdentityMorphism(component[0])] = FiniteSet()
component_morphisms.append(Diagram(current_morphisms))
return component_morphisms
def __new__(cls, name, objects=EmptySet(),
commutative_diagrams=EmptySet()):
if not name:
raise ValueError("A Category cannot have an empty name.")
new_category = Basic.__new__(cls, Symbol(name), Class(objects),
FiniteSet(commutative_diagrams))
return new_category
def group_to_finiteset(group):
"""
Converts ``group`` to a :class:``FiniteSet`` if it is an
iterable.
"""
if iterable(group):
return FiniteSet(group)
else:
return group
def edges(self):
"""
Given the faces of the polyhedra we can get the edges.
Examples
========
>>> from sympy.combinatorics import Polyhedron
>>> from sympy.abc import a, b, c
>>> corners = (a, b, c)
>>> faces = [(0, 1, 2)]
>>> Polyhedron(corners, faces).edges
{(0, 1), (0, 2), (1, 2)}
"""
if self._edges is None:
output = set()
for face in self.faces:
for i in range(len(face)):
edge = tuple(sorted([face[i], face[i - 1]]))
output.add(edge)
self._edges = FiniteSet(*output)
return self._edges
def __new__(cls, corners, faces=[], pgroup=[]):
"""
The constructor of the Polyhedron group object.
It takes up to three parameters: the corners, faces, and
allowed transformations.
The corners/vertices are entered as a list of arbitrary
expressions that are used to identify each vertex.
The faces are entered as a list of tuples of indices; a tuple
of indices identifies the vertices which define the face. They
should be entered in a cw or ccw order; they will be standardized
by reversal and rotation to be give the lowest lexical ordering.
If no faces are given then no edges will be computed.
>>> from sympy.combinatorics.polyhedron import Polyhedron
>>> Polyhedron(list('abc'), [(1, 2, 0)]).faces
{(0, 1, 2)}
>>> Polyhedron(list('abc'), [(1, 0, 2)]).faces
{(0, 1, 2)}
The allowed transformations are entered as allowable permutations
of the vertices for the polyhedron. Instance of Permutations
(as with faces) should refer to the supplied vertices by index.
These permutation are stored as a PermutationGroup.
Examples
========
>>> from sympy.combinatorics.permutations import Permutation
>>> Permutation.print_cyclic = False
>>> from sympy.abc import w, x, y, z
Here we construct the Polyhedron object for a tetrahedron.
>>> corners = [w, x, y, z]
>>> faces = [(0,1,2), (0,2,3), (0,3,1), (1,2,3)]
Next, allowed transformations of the polyhedron must be given. This
is given as permutations of vertices.
Although the vertices of a tetrahedron can be numbered in 24 (4!)
different ways, there are only 12 different orientations for a
physical tetrahedron. The following permutations, applied once or
twice, will generate all 12 of the orientations. (The identity
permutation, Permutation(range(4)), is not included since it does
not change the orientation of the vertices.)
>>> pgroup = [Permutation([[0,1,2], [3]]), \
Permutation([[0,1,3], [2]]), \
Permutation([[0,2,3], [1]]), \
Permutation([[1,2,3], [0]]), \
Permutation([[0,1], [2,3]]), \
Permutation([[0,2], [1,3]]), \
Permutation([[0,3], [1,2]])]
The Polyhedron is now constructed and demonstrated:
>>> tetra = Polyhedron(corners, faces, pgroup)
>>> tetra.size
4
>>> tetra.edges
{(0, 1), (0, 2), (0, 3), (1, 2), (1, 3), (2, 3)}
>>> tetra.corners
(w, x, y, z)
It can be rotated with an arbitrary permutation of vertices, e.g.
the following permutation is not in the pgroup:
>>> tetra.rotate(Permutation([0, 1, 3, 2]))
>>> tetra.corners
(w, x, z, y)
An allowed permutation of the vertices can be constructed by
repeatedly applying permutations from the pgroup to the vertices.
Here is a demonstration that applying p and p**2 for every p in
pgroup generates all the orientations of a tetrahedron and no others:
>>> all = ( (w, x, y, z), \
(x, y, w, z), \
(y, w, x, z), \
(w, z, x, y), \
(z, w, y, x), \
(w, y, z, x), \
(y, z, w, x), \
(x, z, y, w), \
(z, y, x, w), \
(y, x, z, w), \
(x, w, z, y), \
(z, x, w, y) )
>>> got = []
>>> for p in (pgroup + [p**2 for p in pgroup]):
... h = Polyhedron(corners)
... h.rotate(p)
... got.append(h.corners)
...
>>> set(got) == set(all)
True
The make_perm method of a PermutationGroup will randomly pick
permutations, multiply them together, and return the permutation that
can be applied to the polyhedron to give the orientation produced
by those individual permutations.
Here, 3 permutations are used:
>>> tetra.pgroup.make_perm(3) # doctest: +SKIP
Permutation([0, 3, 1, 2])
To select the permutations that should be used, supply a list
of indices to the permutations in pgroup in the order they should
be applied:
>>> use = [0, 0, 2]
>>> p002 = tetra.pgroup.make_perm(3, use)
>>> p002
Permutation([1, 0, 3, 2])
Apply them one at a time:
>>> tetra.reset()
>>> for i in use:
... tetra.rotate(pgroup[i])
...
>>> tetra.vertices
(x, w, z, y)
>>> sequentially = tetra.vertices
Apply the composite permutation:
>>> tetra.reset()
>>> tetra.rotate(p002)
>>> tetra.corners
(x, w, z, y)
>>> tetra.corners in all and tetra.corners == sequentially
True
Notes
=====
Defining permutation groups
---------------------------
It is not necessary to enter any permutations, nor is necessary to
enter a complete set of transforations. In fact, for a polyhedron,
all configurations can be constructed from just two permutations.
For example, the orientations of a tetrahedron can be generated from
an axis passing through a vertex and face and another axis passing
through a different vertex or from an axis passing through the
midpoints of two edges opposite of each other.
For simplicity of presentation, consider a square --
not a cube -- with vertices 1, 2, 3, and 4:
1-----2 We could think of axes of rotation being:
| | 1) through the face
| | 2) from midpoint 1-2 to 3-4 or 1-3 to 2-4
3-----4 3) lines 1-4 or 2-3
To determine how to write the permutations, imagine 4 cameras,
one at each corner, labeled A-D:
A B A B
1-----2 1-----3 vertex index:
| | | | 1 0
| | | | 2 1
3-----4 2-----4 3 2
C D C D 4 3
original after rotation
along 1-4
A diagonal and a face axis will be chosen for the "permutation group"
from which any orientation can be constructed.
>>> pgroup = []
Imagine a clockwise rotation when viewing 1-4 from camera A. The new
orientation is (in camera-order): 1, 3, 2, 4 so the permutation is
given using the *indices* of the vertices as:
>>> pgroup.append(Permutation((0, 2, 1, 3)))
Now imagine rotating clockwise when looking down an axis entering the
center of the square as viewed. The new camera-order would be
3, 1, 4, 2 so the permutation is (using indices):
>>> pgroup.append(Permutation((2, 0, 3, 1)))
The square can now be constructed:
** use real-world labels for the vertices, entering them in
camera order
** for the faces we use zero-based indices of the vertices
in *edge-order* as the face is traversed; neither the
direction nor the starting point matter -- the faces are
only used to define edges (if so desired).
>>> square = Polyhedron((1, 2, 3, 4), [(0, 1, 3, 2)], pgroup)
To rotate the square with a single permutation we can do:
>>> square.rotate(square.pgroup[0]); square.corners
(1, 3, 2, 4)
To use more than one permutation (or to use one permutation more
than once) it is more convenient to use the make_perm method:
>>> p011 = square.pgroup.make_perm([0,1,1]) # diag flip + 2 rotations
>>> square.reset() # return to initial orientation
>>> square.rotate(p011); square.corners
(4, 2, 3, 1)
Thinking outside the box
------------------------
Although the Polyhedron object has a direct physical meaning, it
actually has broader application. In the most general sense it is
just a decorated PermutationGroup, allowing one to connect the
permutations to something physical. For example, a Rubik's cube is
not a proper polyhedron, but the Polyhedron class can be used to
represent it in a way that helps to visualize the Rubik's cube.
>>> from sympy.utilities.iterables import flatten, unflatten
>>> from sympy import symbols
>>> from sympy.combinatorics import RubikGroup
>>> facelets = flatten([symbols(s+'1:5') for s in 'UFRBLD'])
>>> def show():
... pairs = unflatten(r2.corners, 2)
... print(pairs[::2])
... print(pairs[1::2])
...
>>> r2 = Polyhedron(facelets, pgroup=RubikGroup(2))
>>> show()
[(U1, U2), (F1, F2), (R1, R2), (B1, B2), (L1, L2), (D1, D2)]
[(U3, U4), (F3, F4), (R3, R4), (B3, B4), (L3, L4), (D3, D4)]
>>> r2.rotate(0) # cw rotation of F
>>> show()
[(U1, U2), (F3, F1), (U3, R2), (B1, B2), (L1, D1), (R3, R1)]
[(L4, L2), (F4, F2), (U4, R4), (B3, B4), (L3, D2), (D3, D4)]
Predefined Polyhedra
====================
For convenience, the vertices and faces are defined for the following
standard solids along with a permutation group for transformations.
When the polyhedron is oriented as indicated below, the vertices in
a given horizontal plane are numbered in ccw direction, starting from
the vertex that will give the lowest indices in a given face. (In the
net of the vertices, indices preceded by "-" indicate replication of
the lhs index in the net.)
tetrahedron, tetrahedron_faces
------------------------------
4 vertices (vertex up) net:
0 0-0
1 2 3-1
4 faces:
(0,1,2) (0,2,3) (0,3,1) (1,2,3)
cube, cube_faces
----------------
8 vertices (face up) net:
0 1 2 3-0
4 5 6 7-4
6 faces:
(0,1,2,3)
(0,1,5,4) (1,2,6,5) (2,3,7,6) (0,3,7,4)
(4,5,6,7)
octahedron, octahedron_faces
----------------------------
6 vertices (vertex up) net:
0 0 0-0
1 2 3 4-1
5 5 5-5
8 faces:
(0,1,2) (0,2,3) (0,3,4) (0,1,4)
(1,2,5) (2,3,5) (3,4,5) (1,4,5)
dodecahedron, dodecahedron_faces
--------------------------------
20 vertices (vertex up) net:
0 1 2 3 4 -0
5 6 7 8 9 -5
14 10 11 12 13-14
15 16 17 18 19-15
12 faces:
(0,1,2,3,4)
(0,1,6,10,5) (1,2,7,11,6) (2,3,8,12,7) (3,4,9,13,8) (0,4,9,14,5)
(5,10,16,15,14) (
6,10,16,17,11) (7,11,17,18,12) (8,12,18,19,13) (9,13,19,15,14)
(15,16,17,18,19)
icosahedron, icosahedron_faces
------------------------------
12 vertices (face up) net:
0 0 0 0 -0
1 2 3 4 5 -1
6 7 8 9 10 -6
11 11 11 11 -11
20 faces:
(0,1,2) (0,2,3) (0,3,4) (0,4,5) (0,1,5)
(1,2,6) (2,3,7) (3,4,8) (4,5,9) (1,5,10)
(2,6,7) (3,7,8) (4,8,9) (5,9,10) (1,6,10)
(6,7,11,) (7,8,11) (8,9,11) (9,10,11) (6,10,11)
>>> from sympy.combinatorics.polyhedron import cube
>>> cube.edges
{(0, 1), (0, 3), (0, 4), '...', (4, 7), (5, 6), (6, 7)}
If you want to use letters or other names for the corners you
can still use the pre-calculated faces:
>>> corners = list('abcdefgh')
>>> Polyhedron(corners, cube.faces).corners
(a, b, c, d, e, f, g, h)
References
==========
[1] www.ocf.berkeley.edu/~wwu/articles/platonicsolids.pdf
"""
faces = [minlex(f, directed=False, is_set=True) for f in faces]
corners, faces, pgroup = args = \
[Tuple(*a) for a in (corners, faces, pgroup)]
obj = Basic.__new__(cls, *args)
obj._corners = tuple(corners) # in order given
obj._faces = FiniteSet(faces)
if pgroup and pgroup[0].size != len(corners):
raise ValueError("Permutation size unequal to number of corners.")
# use the identity permutation if none are given
obj._pgroup = PermutationGroup((
pgroup or [Perm(range(len(corners)))] ))
return obj
def __new__(cls, *args):
"""
Construct a new instance of Diagram.
If no arguments are supplied, an empty diagram is created.
If at least an argument is supplied, ``args[0]`` is
interpreted as the premises of the diagram. If ``args[0]`` is
a list, it is interpreted as a list of :class:`Morphism`'s, in
which each :class:`Morphism` has an empty set of properties.
If ``args[0]`` is a Python dictionary or a :class:`Dict`, it
is interpreted as a dictionary associating to some
:class:`Morphism`'s some properties.
If at least two arguments are supplied ``args[1]`` is
interpreted as the conclusions of the diagram. The type of
``args[1]`` is interpreted in exactly the same way as the type
of ``args[0]``. If only one argument is supplied, the diagram
has no conclusions.
Examples
========
>>> from sympy.categories import Object, NamedMorphism
>>> from sympy.categories import IdentityMorphism, Diagram
>>> A = Object("A")
>>> B = Object("B")
>>> C = Object("C")
>>> f = NamedMorphism(A, B, "f")
>>> g = NamedMorphism(B, C, "g")
>>> d = Diagram([f, g])
>>> IdentityMorphism(A) in d.premises.keys()
True
>>> g * f in d.premises.keys()
True
>>> d = Diagram([f, g], {g * f: "unique"})
>>> d.conclusions[g * f]
{unique}
"""
premises = {}
conclusions = {}
# Here we will keep track of the objects which appear in the
# premises.
objects = EmptySet()
if len(args) >= 1:
# We've got some premises in the arguments.
premises_arg = args[0]
if isinstance(premises_arg, list):
# The user has supplied a list of morphisms, none of
# which have any attributes.
empty = EmptySet()
for morphism in premises_arg:
objects |= FiniteSet(morphism.domain, morphism.codomain)
Diagram._add_morphism_closure(premises, morphism, empty)
elif isinstance(premises_arg, dict) or isinstance(
premises_arg, Dict):
# The user has supplied a dictionary of morphisms and
# their properties.
for morphism, props in premises_arg.items():
objects |= FiniteSet(morphism.domain, morphism.codomain)
Diagram._add_morphism_closure(premises, morphism,
FiniteSet(props))
if len(args) >= 2:
# We also have some conclusions.
conclusions_arg = args[1]
if isinstance(conclusions_arg, list):
# The user has supplied a list of morphisms, none of
# which have any attributes.
empty = EmptySet()
for morphism in conclusions_arg:
# Check that no new objects appear in conclusions.
if (morphism.domain in objects) and \
(morphism.codomain in objects):
# No need to add identities and recurse
# composites this time.
Diagram._add_morphism_closure(conclusions,
morphism,
empty,
add_identities=False,
recurse_composites=False)
elif isinstance(conclusions_arg, dict) or \
isinstance(conclusions_arg, Dict):
# The user has supplied a dictionary of morphisms and
# their properties.
for morphism, props in conclusions_arg.items():
# Check that no new objects appear in conclusions.
if (morphism.domain in objects) and \
(morphism.codomain in objects):
# No need to add identities and recurse
# composites this time.
Diagram._add_morphism_closure(conclusions,
morphism,
FiniteSet(props),
add_identities=False,
recurse_composites=False)
return Basic.__new__(cls, Dict(premises), Dict(conclusions), objects)
def _generic_layout(diagram, merged_morphisms):
"""
Produces the generic layout for the supplied diagram.
"""
all_objects = set(diagram.objects)
if len(all_objects) == 1:
# There only one object in the diagram, just put in on 1x1
# grid.
grid = _GrowableGrid(1, 1)
grid[0, 0] = tuple(all_objects)[0]
return grid
skeleton = DiagramGrid._build_skeleton(merged_morphisms)
grid = _GrowableGrid(2, 1)
if len(skeleton) == 1:
# This diagram contains only one morphism. Draw it
# horizontally.
objects = sorted(all_objects, key=default_sort_key)
grid[0, 0] = objects[0]
grid[0, 1] = objects[1]
return grid
triangles = DiagramGrid._list_triangles(skeleton)
triangles = DiagramGrid._drop_redundant_triangles(triangles, skeleton)
triangle_sizes = DiagramGrid._compute_triangle_min_sizes(
triangles, skeleton)
triangles = sorted(triangles, key=lambda tri:
DiagramGrid._triangle_key(tri, triangle_sizes))
# Place the first edge on the grid.
root_edge = DiagramGrid._pick_root_edge(triangles[0], skeleton)
grid[0, 0], grid[0, 1] = root_edge
fringe = [((0, 0), (0, 1))]
# Record which objects we now have on the grid.
placed_objects = set(root_edge)
while placed_objects != all_objects:
welding = DiagramGrid._find_triangle_to_weld(triangles, fringe, grid)
if welding:
(triangle, welding_edge) = welding
restart_required = DiagramGrid._weld_triangle(
triangle, welding_edge, fringe, grid, skeleton)
if restart_required:
continue
placed_objects.update(
DiagramGrid._triangle_objects(triangle))
else:
# No more weldings found. Try to attach triangles by
# vertices.
new_obj = DiagramGrid._grow_pseudopod(
triangles, fringe, grid, skeleton, placed_objects)
if not new_obj:
# No more triangles can be attached, not even by
# the edge. We will set up a new diagram out of
# what has been left, laid it out independently,
# and then attach it to this one.
remaining_objects = all_objects - placed_objects
remaining_diagram = diagram.subdiagram_from_objects(
FiniteSet(remaining_objects))
remaining_grid = DiagramGrid(remaining_diagram)
# Now, let's glue ``remaining_grid`` to ``grid``.
final_width = grid.width + remaining_grid.width
final_height = max(grid.height, remaining_grid.height)
final_grid = _GrowableGrid(final_width, final_height)
for i in xrange(grid.width):
for j in xrange(grid.height):
final_grid[i, j] = grid[i, j]
start_j = grid.width
for i in xrange(remaining_grid.height):
for j in xrange(remaining_grid.width):
final_grid[i, start_j + j] = remaining_grid[i, j]
return final_grid
placed_objects.add(new_obj)
triangles = DiagramGrid._drop_irrelevant_triangles(
triangles, placed_objects)
return grid
def _grow_pseudopod(triangles, fringe, grid, skeleton, placed_objects):
"""
Starting from an object in the existing structure on the grid,
adds an edge to which a triangle from ``triangles`` could be
welded. If this method has found a way to do so, it returns
the object it has just added.
This method should be applied when ``_weld_triangle`` cannot
find weldings any more.
"""
for i in xrange(grid.height):
for j in xrange(grid.width):
obj = grid[i, j]
if not obj:
continue
# Here we need to choose a triangle which has only
# ``obj`` in common with the existing structure. The
# situations when this is not possible should be
# handled elsewhere.
def good_triangle(tri):
objs = DiagramGrid._triangle_objects(tri)
return obj in objs and \
placed_objects & (objs - set([obj])) == set()
tris = [tri for tri in triangles if good_triangle(tri)]
if not tris:
# This object is not interesting.
continue
# Pick the "simplest" of the triangles which could be
# attached. Remember that the list of triangles is
# sorted according to their "simplicity" (see
# _compute_triangle_min_sizes for the metric).
#
# Note that ``tris`` are sequentially built from
# ``triangles``, so we don't have to worry about hash
# randomisation.
tri = tris[0]
# We have found a triangle which could be attached to
# the existing structure by a vertex.
candidates = sorted([e for e in tri if skeleton[e]],
key=lambda e: FiniteSet(e).sort_key())
edges = [e for e in candidates if obj in e]
# Note that a meaningful edge (i.e., and edge that is
# associated with a morphism) containing ``obj``
# always exists. That's because all triangles are
# guaranteed to have at least two meaningful edges.
# See _drop_redundant_triangles.
# Get the object at the other end of the edge.
edge = edges[0]
other_obj = tuple(edge - frozenset([obj]))[0]
# Now check for free directions. When checking for
# free directions, prefer the horizontal and vertical
# directions.
neighbours = [(i-1, j), (i, j+1), (i+1, j), (i, j-1),
(i-1,j-1), (i-1, j+1), (i+1,j-1), (i+1, j+1)]
for pt in neighbours:
if DiagramGrid._empty_point(pt, grid):
# We have a found a place to grow the
# pseudopod into.
offset = DiagramGrid._put_object(
pt, other_obj, grid, fringe)
i += offset[0]
j += offset[1]
pt = (pt[0] + offset[0], pt[1] + offset[1])
fringe.append(((i, j), pt))
return other_obj
# This diagram is actually cooler that I can handle. Fail cowardly.
return None