/

# Category Theory Module¶

## Introduction¶

The category theory module for SymPy will allow manipulating diagrams within a single category, including drawing them in TikZ and deciding whether they are commutative or not.

The general reference work this module tries to follow is

[JoyOfCats] J. Adamek, H. Herrlich. G. E. Strecker: Abstract and
Concrete Categories. The Joy of Cats.

katmat.math.uni-bremen.de/acc/acc.pdf

The module is still in its pre-embryonic stage.

## Base Class Reference¶

This section lists the classes which implement some of the basic notions in category theory: objects, morphisms, categories, and diagrams.

class sympy.categories.Object

The base class for any kind of object in an abstract category.

While technically any instance of Basic will do, this class is the recommended way to create abstract objects in abstract categories.

class sympy.categories.Morphism

The base class for any morphism in an abstract category.

In abstract categories, a morphism is an arrow between two category objects. The object where the arrow starts is called the domain, while the object where the arrow ends is called the codomain.

Two morphisms between the same pair of objects are considered to be the same morphisms. To distinguish between morphisms between the same objects use NamedMorphism.

It is prohibited to instantiate this class. Use one of the derived classes instead.

codomain

Returns the codomain of the morphism.

Examples

>>> from sympy.categories import Object, NamedMorphism
>>> A = Object("A")
>>> B = Object("B")
>>> f = NamedMorphism(A, B, "f")
>>> f.codomain
Object("B")

compose(other)

Composes self with the supplied morphism.

The order of elements in the composition is the usual order, i.e., to construct $$g\circ f$$ use g.compose(f).

Examples

>>> from sympy.categories import Object, NamedMorphism
>>> A = Object("A")
>>> B = Object("B")
>>> C = Object("C")
>>> f = NamedMorphism(A, B, "f")
>>> g = NamedMorphism(B, C, "g")
>>> g * f
CompositeMorphism((NamedMorphism(Object("A"), Object("B"), "f"),
NamedMorphism(Object("B"), Object("C"), "g")))
>>> (g * f).domain
Object("A")
>>> (g * f).codomain
Object("C")

domain

Returns the domain of the morphism.

Examples

>>> from sympy.categories import Object, NamedMorphism
>>> A = Object("A")
>>> B = Object("B")
>>> f = NamedMorphism(A, B, "f")
>>> f.domain
Object("A")

class sympy.categories.NamedMorphism

Represents a morphism which has a name.

Names are used to distinguish between morphisms which have the same domain and codomain: two named morphisms are equal if they have the same domains, codomains, and names.

Morphism

Examples

>>> from sympy.categories import Object, NamedMorphism
>>> A = Object("A")
>>> B = Object("B")
>>> f = NamedMorphism(A, B, "f")
>>> f
NamedMorphism(Object("A"), Object("B"), "f")
>>> f.name
'f'

name

Returns the name of the morphism.

Examples

>>> from sympy.categories import Object, NamedMorphism
>>> A = Object("A")
>>> B = Object("B")
>>> f = NamedMorphism(A, B, "f")
>>> f.name
'f'

class sympy.categories.CompositeMorphism

Represents a morphism which is a composition of other morphisms.

Two composite morphisms are equal if the morphisms they were obtained from (components) are the same and were listed in the same order.

The arguments to the constructor for this class should be listed in diagram order: to obtain the composition $$g\circ f$$ from the instances of Morphism g and f use CompositeMorphism(f, g).

Examples

>>> from sympy.categories import Object, NamedMorphism, CompositeMorphism
>>> A = Object("A")
>>> B = Object("B")
>>> C = Object("C")
>>> f = NamedMorphism(A, B, "f")
>>> g = NamedMorphism(B, C, "g")
>>> g * f
CompositeMorphism((NamedMorphism(Object("A"), Object("B"), "f"),
NamedMorphism(Object("B"), Object("C"), "g")))
>>> CompositeMorphism(f, g) == g * f
True

codomain

Returns the codomain of this composite morphism.

The codomain of the composite morphism is the codomain of its last component.

Examples

>>> from sympy.categories import Object, NamedMorphism
>>> A = Object("A")
>>> B = Object("B")
>>> C = Object("C")
>>> f = NamedMorphism(A, B, "f")
>>> g = NamedMorphism(B, C, "g")
>>> (g * f).codomain
Object("C")

components

Returns the components of this composite morphism.

Examples

>>> from sympy.categories import Object, NamedMorphism
>>> A = Object("A")
>>> B = Object("B")
>>> C = Object("C")
>>> f = NamedMorphism(A, B, "f")
>>> g = NamedMorphism(B, C, "g")
>>> (g * f).components
(NamedMorphism(Object("A"), Object("B"), "f"),
NamedMorphism(Object("B"), Object("C"), "g"))

domain

Returns the domain of this composite morphism.

The domain of the composite morphism is the domain of its first component.

Examples

>>> from sympy.categories import Object, NamedMorphism
>>> A = Object("A")
>>> B = Object("B")
>>> C = Object("C")
>>> f = NamedMorphism(A, B, "f")
>>> g = NamedMorphism(B, C, "g")
>>> (g * f).domain
Object("A")

flatten(new_name)

Forgets the composite structure of this morphism.

If new_name is not empty, returns a NamedMorphism with the supplied name, otherwise returns a Morphism. In both cases the domain of the new morphism is the domain of this composite morphism and the codomain of the new morphism is the codomain of this composite morphism.

Examples

>>> from sympy.categories import Object, NamedMorphism
>>> A = Object("A")
>>> B = Object("B")
>>> C = Object("C")
>>> f = NamedMorphism(A, B, "f")
>>> g = NamedMorphism(B, C, "g")
>>> (g * f).flatten("h")
NamedMorphism(Object("A"), Object("C"), "h")

class sympy.categories.IdentityMorphism

Represents an identity morphism.

An identity morphism is a morphism with equal domain and codomain, which acts as an identity with respect to composition.

Morphism

Examples

>>> from sympy.categories import Object, NamedMorphism, IdentityMorphism
>>> A = Object("A")
>>> B = Object("B")
>>> f = NamedMorphism(A, B, "f")
>>> id_A = IdentityMorphism(A)
>>> id_B = IdentityMorphism(B)
>>> f * id_A == f
True
>>> id_B * f == f
True

class sympy.categories.Category

An (abstract) category.

A category [JoyOfCats] is a quadruple $$\mbox{K} = (O, \hom, id, \circ)$$ consisting of

• a (set-theoretical) class $$O$$, whose members are called $$K$$-objects,
• for each pair $$(A, B)$$ of $$K$$-objects, a set $$\hom(A, B)$$ whose members are called $$K$$-morphisms from $$A$$ to $$B$$,
• for a each $$K$$-object $$A$$, a morphism $$id:A\rightarrow A$$, called the $$K$$-identity of $$A$$,
• a composition law $$\circ$$ associating with every $$K$$-morphisms $$f:A\rightarrow B$$ and $$g:B\rightarrow C$$ a $$K$$-morphism $$g\circ f:A\rightarrow C$$, called the composite of $$f$$ and $$g$$.

Composition is associative, $$K$$-identities are identities with respect to composition, and the sets $$\hom(A, B)$$ are pairwise disjoint.

This class knows nothing about its objects and morphisms. Concrete cases of (abstract) categories should be implemented as classes derived from this one.

Certain instances of Diagram can be asserted to be commutative in a Category by supplying the argument commutative_diagrams in the constructor.

Diagram

Examples

>>> from sympy.categories import Object, NamedMorphism, Diagram, Category
>>> from sympy import FiniteSet
>>> A = Object("A")
>>> B = Object("B")
>>> C = Object("C")
>>> f = NamedMorphism(A, B, "f")
>>> g = NamedMorphism(B, C, "g")
>>> d = Diagram([f, g])
>>> K = Category("K", commutative_diagrams=[d])
>>> K.commutative_diagrams == FiniteSet(d)
True

commutative_diagrams

Returns the FiniteSet of diagrams which are known to be commutative in this category.

>>> from sympy.categories import Object, NamedMorphism, Diagram, Category
>>> from sympy import FiniteSet
>>> A = Object("A")
>>> B = Object("B")
>>> C = Object("C")
>>> f = NamedMorphism(A, B, "f")
>>> g = NamedMorphism(B, C, "g")
>>> d = Diagram([f, g])
>>> K = Category("K", commutative_diagrams=[d])
>>> K.commutative_diagrams == FiniteSet(d)
True

name

Returns the name of this category.

Examples

>>> from sympy.categories import Category
>>> K = Category("K")
>>> K.name
'K'

objects

Returns the class of objects of this category.

Examples

>>> from sympy.categories import Object, Category
>>> from sympy import FiniteSet
>>> A = Object("A")
>>> B = Object("B")
>>> K = Category("K", FiniteSet(A, B))
>>> K.objects
Class({Object("A"), Object("B")})

class sympy.categories.Diagram

Represents a diagram in a certain category.

Informally, a diagram is a collection of objects of a category and certain morphisms between them. A diagram is still a monoid with respect to morphism composition; i.e., identity morphisms, as well as all composites of morphisms included in the diagram belong to the diagram. For a more formal approach to this notion see [Pare1970].

The components of composite morphisms are also added to the diagram. No properties are assigned to such morphisms by default.

A commutative diagram is often accompanied by a statement of the following kind: “if such morphisms with such properties exist, then such morphisms which such properties exist and the diagram is commutative”. To represent this, an instance of Diagram includes a collection of morphisms which are the premises and another collection of conclusions. premises and conclusions associate morphisms belonging to the corresponding categories with the FiniteSet‘s of their properties.

The set of properties of a composite morphism is the intersection of the sets of properties of its components. The domain and codomain of a conclusion morphism should be among the domains and codomains of the morphisms listed as the premises of a diagram.

No checks are carried out of whether the supplied object and morphisms do belong to one and the same category.

References

[Pare1970] B. Pareigis: Categories and functors. Academic Press, 1970.

Examples

>>> from sympy.categories import Object, NamedMorphism, Diagram
>>> from sympy import FiniteSet, pprint, default_sort_key
>>> A = Object("A")
>>> B = Object("B")
>>> C = Object("C")
>>> f = NamedMorphism(A, B, "f")
>>> g = NamedMorphism(B, C, "g")
>>> d = Diagram([f, g])
>>> premises_keys = sorted(list(d.premises.keys()), key=default_sort_key)
>>> pprint(premises_keys, use_unicode=False)
[g*f:A-->C, id:A-->A, id:B-->B, id:C-->C, f:A-->B, g:B-->C]
>>> pprint(d.premises, use_unicode=False)
{g*f:A-->C: EmptySet(), id:A-->A: EmptySet(), id:B-->B: EmptySet(), id:C-->C:
EmptySet(), f:A-->B: EmptySet(), g:B-->C: EmptySet()}
>>> d = Diagram([f, g], {g * f: "unique"})
>>> pprint(d.conclusions)
{g*f:A-->C: {unique}}

conclusions

Returns the conclusions of this diagram.

Examples

>>> from sympy.categories import Object, NamedMorphism
>>> from sympy.categories import IdentityMorphism, Diagram
>>> from sympy import FiniteSet
>>> 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 list(d.premises.keys())
True
>>> g * f in list(d.premises.keys())
True
>>> d = Diagram([f, g], {g * f: "unique"})
>>> d.conclusions[g * f] == FiniteSet("unique")
True

hom(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})

is_subdiagram(diagram)

Checks whether diagram is a subdiagram of self. Diagram $$D'$$ is a subdiagram of $$D$$ if all premises (conclusions) of $$D'$$ are contained in the premises (conclusions) of $$D$$. The morphisms contained both in $$D'$$ and $$D$$ should have the same properties for $$D'$$ to be a subdiagram of $$D$$.

Examples

>>> from sympy.categories import Object, NamedMorphism, Diagram
>>> 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"})
>>> d1 = Diagram([f])
>>> d.is_subdiagram(d1)
True
>>> d1.is_subdiagram(d)
False

objects

Returns the FiniteSet of objects that appear in this diagram.

Examples

>>> from sympy.categories import Object, NamedMorphism, Diagram
>>> A = Object("A")
>>> B = Object("B")
>>> C = Object("C")
>>> f = NamedMorphism(A, B, "f")
>>> g = NamedMorphism(B, C, "g")
>>> d = Diagram([f, g])
>>> d.objects
{Object("A"), Object("B"), Object("C")}

premises

Returns the premises of this diagram.

Examples

>>> from sympy.categories import Object, NamedMorphism
>>> from sympy.categories import IdentityMorphism, Diagram
>>> from sympy import pretty
>>> A = Object("A")
>>> B = Object("B")
>>> f = NamedMorphism(A, B, "f")
>>> id_A = IdentityMorphism(A)
>>> id_B = IdentityMorphism(B)
>>> d = Diagram([f])
>>> print(pretty(d.premises, use_unicode=False))
{id:A-->A: EmptySet(), id:B-->B: EmptySet(), f:A-->B: EmptySet()}

subdiagram_from_objects(objects)

If objects is a subset of the objects of self, returns a diagram which has as premises all those premises of self which have a domains and codomains in objects, likewise for conclusions. Properties are preserved.

Examples

>>> from sympy.categories import Object, NamedMorphism, Diagram
>>> from sympy import FiniteSet
>>> A = Object("A")
>>> B = Object("B")
>>> C = Object("C")
>>> f = NamedMorphism(A, B, "f")
>>> g = NamedMorphism(B, C, "g")
>>> d = Diagram([f, g], {f: "unique", g*f: "veryunique"})
>>> d1 = d.subdiagram_from_objects(FiniteSet(A, B))
>>> d1 == Diagram([f], {f: "unique"})
True


## Diagram Drawing¶

This section lists the classes which allow automatic drawing of diagrams.

class sympy.categories.diagram_drawing.DiagramGrid(diagram, groups=None, **hints)[source]

Constructs and holds the fitting of the diagram into a grid.

The mission of this class is to analyse the structure of the supplied diagram and to place its objects on a grid such that, when the objects and the morphisms are actually drawn, the diagram would be “readable”, in the sense that there will not be many intersections of moprhisms. This class does not perform any actual drawing. It does strive nevertheless to offer sufficient metadata to draw a diagram.

Consider the following simple diagram.

>>> from sympy.categories import Object, NamedMorphism
>>> from sympy.categories import Diagram, DiagramGrid
>>> from sympy import pprint
>>> A = Object("A")
>>> B = Object("B")
>>> C = Object("C")
>>> f = NamedMorphism(A, B, "f")
>>> g = NamedMorphism(B, C, "g")
>>> diagram = Diagram([f, g])


The simplest way to have a diagram laid out is the following:

>>> grid = DiagramGrid(diagram)
>>> (grid.width, grid.height)
(2, 2)
>>> pprint(grid)
A  B

C


Sometimes one sees the diagram as consisting of logical groups. One can advise DiagramGrid as to such groups by employing the groups keyword argument.

Consider the following diagram:

>>> D = Object("D")
>>> f = NamedMorphism(A, B, "f")
>>> g = NamedMorphism(B, C, "g")
>>> h = NamedMorphism(D, A, "h")
>>> k = NamedMorphism(D, B, "k")
>>> diagram = Diagram([f, g, h, k])


Lay it out with generic layout:

>>> grid = DiagramGrid(diagram)
>>> pprint(grid)
A  B  D

C


Now, we can group the objects $$A$$ and $$D$$ to have them near one another:

>>> grid = DiagramGrid(diagram, groups=[[A, D], B, C])
>>> pprint(grid)
B     C

A  D


Note how the positioning of the other objects changes.

Further indications can be supplied to the constructor of DiagramGrid using keyword arguments. The currently supported hints are explained in the following paragraphs.

DiagramGrid does not automatically guess which layout would suit the supplied diagram better. Consider, for example, the following linear diagram:

>>> E = Object("E")
>>> f = NamedMorphism(A, B, "f")
>>> g = NamedMorphism(B, C, "g")
>>> h = NamedMorphism(C, D, "h")
>>> i = NamedMorphism(D, E, "i")
>>> diagram = Diagram([f, g, h, i])


When laid out with the generic layout, it does not get to look linear:

>>> grid = DiagramGrid(diagram)
>>> pprint(grid)
A  B

C  D

E


To get it laid out in a line, use layout="sequential":

>>> grid = DiagramGrid(diagram, layout="sequential")
>>> pprint(grid)
A  B  C  D  E


One may sometimes need to transpose the resulting layout. While this can always be done by hand, DiagramGrid provides a hint for that purpose:

>>> grid = DiagramGrid(diagram, layout="sequential", transpose=True)
>>> pprint(grid)
A

B

C

D

E


Separate hints can also be provided for each group. For an example, refer to tests/test_drawing.py, and see the different ways in which the five lemma [FiveLemma] can be laid out.

Diagram

References

[FiveLemma] http://en.wikipedia.org/wiki/Five_lemma

height[source]

Returns the number of rows in this diagram layout.

Examples

>>> from sympy.categories import Object, NamedMorphism
>>> from sympy.categories import Diagram, DiagramGrid
>>> A = Object("A")
>>> B = Object("B")
>>> C = Object("C")
>>> f = NamedMorphism(A, B, "f")
>>> g = NamedMorphism(B, C, "g")
>>> diagram = Diagram([f, g])
>>> grid = DiagramGrid(diagram)
>>> grid.height
2

morphisms[source]

Returns those morphisms (and their properties) which are sufficiently meaningful to be drawn.

Examples

>>> from sympy.categories import Object, NamedMorphism
>>> from sympy.categories import Diagram, DiagramGrid
>>> A = Object("A")
>>> B = Object("B")
>>> C = Object("C")
>>> f = NamedMorphism(A, B, "f")
>>> g = NamedMorphism(B, C, "g")
>>> diagram = Diagram([f, g])
>>> grid = DiagramGrid(diagram)
>>> grid.morphisms
{NamedMorphism(Object("A"), Object("B"), "f"): EmptySet(),
NamedMorphism(Object("B"), Object("C"), "g"): EmptySet()}

width[source]

Returns the number of columns in this diagram layout.

Examples

>>> from sympy.categories import Object, NamedMorphism
>>> from sympy.categories import Diagram, DiagramGrid
>>> A = Object("A")
>>> B = Object("B")
>>> C = Object("C")
>>> f = NamedMorphism(A, B, "f")
>>> g = NamedMorphism(B, C, "g")
>>> diagram = Diagram([f, g])
>>> grid = DiagramGrid(diagram)
>>> grid.width
2