modelparameters.sympy.categories package

Submodules

modelparameters.sympy.categories.baseclasses module

class modelparameters.sympy.categories.baseclasses.Category(name, objects=EmptySet(), commutative_diagrams=EmptySet())[source]

Bases: Basic

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:Arightarrow A, called the K-identity of A,

  • a composition law circ associating with every K-morphisms f:Arightarrow B and g:Brightarrow C a K-morphism gcirc f:Arightarrow 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.

Examples

>>> from ..categories import Object, NamedMorphism, Diagram, Category
>>> from .. 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

See also

Diagram

all_morphisms()[source]
property commutative_diagrams

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

>>> from ..categories import Object, NamedMorphism, Diagram, Category
>>> from .. 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
default_assumptions = {}
hom(A, B)[source]
property name

Returns the name of this category.

Examples

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

Returns the class of objects of this category.

Examples

>>> from ..categories import Object, Category
>>> from .. import FiniteSet
>>> A = Object("A")
>>> B = Object("B")
>>> K = Category("K", FiniteSet(A, B))
>>> K.objects
Class({Object("A"), Object("B")})
class modelparameters.sympy.categories.baseclasses.Class(*args)[source]

Bases: Set

The base class for any kind of class in the set-theoretic sense.

In axiomatic set theories, everything is a class. A class which can be a member of another class is a set. A class which is not a member of another class is a proper class. The class {1, 2} is a set; the class of all sets is a proper class.

This class is essentially a synonym for sympy.core.Set. The goal of this class is to assure easier migration to the eventual proper implementation of set theory.

default_assumptions = {}
is_proper = False
class modelparameters.sympy.categories.baseclasses.CompositeMorphism(*components)[source]

Bases: Morphism

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 gcirc f from the instances of Morphism g and f use CompositeMorphism(f, g).

Examples

>>> from ..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
property codomain

Returns the codomain of this composite morphism.

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

Examples

>>> from ..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")
property components

Returns the components of this composite morphism.

Examples

>>> from ..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"))
default_assumptions = {}
property domain

Returns the domain of this composite morphism.

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

Examples

>>> from ..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)[source]

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 ..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 modelparameters.sympy.categories.baseclasses.Diagram(*args)[source]

Bases: Basic

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.

Examples

>>> from ..categories import Object, NamedMorphism, Diagram
>>> from .. 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(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}}

References

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

property conclusions

Returns the conclusions of this diagram.

Examples

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

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 ..categories import Object, NamedMorphism, Diagram
>>> from .. 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

is_subdiagram(diagram)[source]

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

Returns the FiniteSet of objects that appear in this diagram.

Examples

>>> from ..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")}
property premises

Returns the premises of this diagram.

Examples

>>> from ..categories import Object, NamedMorphism
>>> from ..categories import IdentityMorphism, Diagram
>>> from .. 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)[source]

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 ..categories import Object, NamedMorphism, Diagram
>>> from .. 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
class modelparameters.sympy.categories.baseclasses.IdentityMorphism(domain)[source]

Bases: Morphism

Represents an identity morphism.

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

Examples

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

See also

Morphism

default_assumptions = {}
class modelparameters.sympy.categories.baseclasses.Morphism(domain, codomain)[source]

Bases: Basic

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.

See also

IdentityMorphism, NamedMorphism, CompositeMorphism

property codomain

Returns the codomain of the morphism.

Examples

>>> from ..categories import Object, NamedMorphism
>>> A = Object("A")
>>> B = Object("B")
>>> f = NamedMorphism(A, B, "f")
>>> f.codomain
Object("B")
compose(other)[source]

Composes self with the supplied morphism.

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

Examples

>>> from ..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")
default_assumptions = {}
property domain

Returns the domain of the morphism.

Examples

>>> from ..categories import Object, NamedMorphism
>>> A = Object("A")
>>> B = Object("B")
>>> f = NamedMorphism(A, B, "f")
>>> f.domain
Object("A")
class modelparameters.sympy.categories.baseclasses.NamedMorphism(domain, codomain, name)[source]

Bases: Morphism

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.

Examples

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

See also

Morphism

default_assumptions = {}
property name

Returns the name of the morphism.

Examples

>>> from ..categories import Object, NamedMorphism
>>> A = Object("A")
>>> B = Object("B")
>>> f = NamedMorphism(A, B, "f")
>>> f.name
'f'
class modelparameters.sympy.categories.baseclasses.Object(name, **assumptions)[source]

Bases: Symbol

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.

default_assumptions = {}
name

modelparameters.sympy.categories.diagram_drawing module

This module contains the functionality to arrange the nodes of a diagram on an abstract grid, and then to produce a graphical representation of the grid.

The currently supported back-ends are Xy-pic [Xypic].

Layout Algorithm

This section provides an overview of the algorithms implemented in DiagramGrid to lay out diagrams.

The first step of the algorithm is the removal composite and identity morphisms which do not have properties in the supplied diagram. The premises and conclusions of the diagram are then merged.

The generic layout algorithm begins with the construction of the “skeleton” of the diagram. The skeleton is an undirected graph which has the objects of the diagram as vertices and has an (undirected) edge between each pair of objects between which there exist morphisms. The direction of the morphisms does not matter at this stage. The skeleton also includes an edge between each pair of vertices A and C such that there exists an object B which is connected via a morphism to A, and via a morphism to C.

The skeleton constructed in this way has the property that every object is a vertex of a triangle formed by three edges of the skeleton. This property lies at the base of the generic layout algorithm.

After the skeleton has been constructed, the algorithm lists all triangles which can be formed. Note that some triangles will not have all edges corresponding to morphisms which will actually be drawn. Triangles which have only one edge or less which will actually be drawn are immediately discarded.

The list of triangles is sorted according to the number of edges which correspond to morphisms, then the triangle with the least number of such edges is selected. One of such edges is picked and the corresponding objects are placed horizontally, on a grid. This edge is recorded to be in the fringe. The algorithm then finds a “welding” of a triangle to the fringe. A welding is an edge in the fringe where a triangle could be attached. If the algorithm succeeds in finding such a welding, it adds to the grid that vertex of the triangle which was not yet included in any edge in the fringe and records the two new edges in the fringe. This process continues iteratively until all objects of the diagram has been placed or until no more weldings can be found.

An edge is only removed from the fringe when a welding to this edge has been found, and there is no room around this edge to place another vertex.

When no more weldings can be found, but there are still triangles left, the algorithm searches for a possibility of attaching one of the remaining triangles to the existing structure by a vertex. If such a possibility is found, the corresponding edge of the found triangle is placed in the found space and the iterative process of welding triangles restarts.

When logical groups are supplied, each of these groups is laid out independently. Then a diagram is constructed in which groups are objects and any two logical groups between which there exist morphisms are connected via a morphism. This diagram is laid out. Finally, the grid which includes all objects of the initial diagram is constructed by replacing the cells which contain logical groups with the corresponding laid out grids, and by correspondingly expanding the rows and columns.

The sequential layout algorithm begins by constructing the underlying undirected graph defined by the morphisms obtained after simplifying premises and conclusions and merging them (see above). The vertex with the minimal degree is then picked up and depth-first search is started from it. All objects which are located at distance n from the root in the depth-first search tree, are positioned in the n-th column of the resulting grid. The sequential layout will therefore attempt to lay the objects out along a line.

References

[Xypic] http://xy-pic.sourceforge.net/

class modelparameters.sympy.categories.diagram_drawing.ArrowStringDescription(unit, curving, curving_amount, looping_start, looping_end, horizontal_direction, vertical_direction, label_position, label)[source]

Bases: object

Stores the information necessary for producing an Xy-pic description of an arrow.

The principal goal of this class is to abstract away the string representation of an arrow and to also provide the functionality to produce the actual Xy-pic string.

unit sets the unit which will be used to specify the amount of curving and other distances. horizontal_direction should be a string of "r" or "l" specifying the horizontal offset of the target cell of the arrow relatively to the current one. vertical_direction should specify the vertical offset using a series of either "d" or "u". label_position should be either "^", "_", or "|" to specify that the label should be positioned above the arrow, below the arrow or just over the arrow, in a break. Note that the notions “above” and “below” are relative to arrow direction. label stores the morphism label.

This works as follows (disregard the yet unexplained arguments):

>>> from .diagram_drawing import ArrowStringDescription
>>> astr = ArrowStringDescription(
... unit="mm", curving=None, curving_amount=None,
... looping_start=None, looping_end=None, horizontal_direction="d",
... vertical_direction="r", label_position="_", label="f")
>>> print(str(astr))
\ar[dr]_{f}

curving should be one of "^", "_" to specify in which direction the arrow is going to curve. curving_amount is a number describing how many unit’s the morphism is going to curve:

>>> astr = ArrowStringDescription(
... unit="mm", curving="^", curving_amount=12,
... looping_start=None, looping_end=None, horizontal_direction="d",
... vertical_direction="r", label_position="_", label="f")
>>> print(str(astr))
\ar@/^12mm/[dr]_{f}

looping_start and looping_end are currently only used for loop morphisms, those which have the same domain and codomain. These two attributes should store a valid Xy-pic direction and specify, correspondingly, the direction the arrow gets out into and the direction the arrow gets back from:

>>> astr = ArrowStringDescription(
... unit="mm", curving=None, curving_amount=None,
... looping_start="u", looping_end="l", horizontal_direction="",
... vertical_direction="", label_position="_", label="f")
>>> print(str(astr))
\ar@(u,l)[]_{f}

label_displacement controls how far the arrow label is from the ends of the arrow. For example, to position the arrow label near the arrow head, use “>”:

>>> astr = ArrowStringDescription(
... unit="mm", curving="^", curving_amount=12,
... looping_start=None, looping_end=None, horizontal_direction="d",
... vertical_direction="r", label_position="_", label="f")
>>> astr.label_displacement = ">"
>>> print(str(astr))
\ar@/^12mm/[dr]_>{f}

Finally, arrow_style is used to specify the arrow style. To get a dashed arrow, for example, use “{–>}” as arrow style:

>>> astr = ArrowStringDescription(
... unit="mm", curving="^", curving_amount=12,
... looping_start=None, looping_end=None, horizontal_direction="d",
... vertical_direction="r", label_position="_", label="f")
>>> astr.arrow_style = "{-->}"
>>> print(str(astr))
\ar@/^12mm/@{-->}[dr]_{f}

Notes

Instances of ArrowStringDescription will be constructed by XypicDiagramDrawer and provided for further use in formatters. The user is not expected to construct instances of ArrowStringDescription themselves.

To be able to properly utilise this class, the reader is encouraged to checkout the Xy-pic user guide, available at [Xypic].

See also

XypicDiagramDrawer

References

[Xypic] http://xy-pic.sourceforge.net/

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

Bases: object

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 ..categories import Object, NamedMorphism
>>> from ..categories import Diagram, DiagramGrid
>>> from .. 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.

See also

Diagram

References

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

property height

Returns the number of rows in this diagram layout.

Examples

>>> from ..categories import Object, NamedMorphism
>>> from ..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
property morphisms

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

Examples

>>> from ..categories import Object, NamedMorphism
>>> from ..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()}
property width

Returns the number of columns in this diagram layout.

Examples

>>> from ..categories import Object, NamedMorphism
>>> from ..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
class modelparameters.sympy.categories.diagram_drawing.XypicDiagramDrawer[source]

Bases: object

Given a Diagram and the corresponding DiagramGrid, produces the Xy-pic representation of the diagram.

The most important method in this class is draw. Consider the following triangle diagram:

>>> from ..categories import Object, NamedMorphism, Diagram
>>> from ..categories import DiagramGrid, XypicDiagramDrawer
>>> A = Object("A")
>>> B = Object("B")
>>> C = Object("C")
>>> f = NamedMorphism(A, B, "f")
>>> g = NamedMorphism(B, C, "g")
>>> diagram = Diagram([f, g], {g * f: "unique"})

To draw this diagram, its objects need to be laid out with a DiagramGrid:

>>> grid = DiagramGrid(diagram)

Finally, the drawing:

>>> drawer = XypicDiagramDrawer()
>>> print(drawer.draw(diagram, grid))
\xymatrix{
A \ar[d]_{g\circ f} \ar[r]^{f} & B \ar[ld]^{g} \\
C &
}

For further details see the docstring of this method.

To control the appearance of the arrows, formatters are used. The dictionary arrow_formatters maps morphisms to formatter functions. A formatter is accepts an ArrowStringDescription and is allowed to modify any of the arrow properties exposed thereby. For example, to have all morphisms with the property unique appear as dashed arrows, and to have their names prepended with exists !, the following should be done:

>>> def formatter(astr):
...   astr.label = "\exists !" + astr.label
...   astr.arrow_style = "{-->}"
>>> drawer.arrow_formatters["unique"] = formatter
>>> print(drawer.draw(diagram, grid))
\xymatrix{
A \ar@{-->}[d]_{\exists !g\circ f} \ar[r]^{f} & B \ar[ld]^{g} \\
C &
}

To modify the appearance of all arrows in the diagram, set default_arrow_formatter. For example, to place all morphism labels a little bit farther from the arrow head so that they look more centred, do as follows:

>>> def default_formatter(astr):
...   astr.label_displacement = "(0.45)"
>>> drawer.default_arrow_formatter = default_formatter
>>> print(drawer.draw(diagram, grid))
\xymatrix{
A \ar@{-->}[d]_(0.45){\exists !g\circ f} \ar[r]^(0.45){f} & B \ar[ld]^(0.45){g} \\
C &
}

In some diagrams some morphisms are drawn as curved arrows. Consider the following diagram:

>>> D = Object("D")
>>> E = Object("E")
>>> h = NamedMorphism(D, A, "h")
>>> k = NamedMorphism(D, B, "k")
>>> diagram = Diagram([f, g, h, k])
>>> grid = DiagramGrid(diagram)
>>> drawer = XypicDiagramDrawer()
>>> print(drawer.draw(diagram, grid))
\xymatrix{
A \ar[r]_{f} & B \ar[d]^{g} & D \ar[l]^{k} \ar@/_3mm/[ll]_{h} \\
& C &
}

To control how far the morphisms are curved by default, one can use the unit and default_curving_amount attributes:

>>> drawer.unit = "cm"
>>> drawer.default_curving_amount = 1
>>> print(drawer.draw(diagram, grid))
\xymatrix{
A \ar[r]_{f} & B \ar[d]^{g} & D \ar[l]^{k} \ar@/_1cm/[ll]_{h} \\
& C &
}

In some diagrams, there are multiple curved morphisms between the same two objects. To control by how much the curving changes between two such successive morphisms, use default_curving_step:

>>> drawer.default_curving_step = 1
>>> h1 = NamedMorphism(A, D, "h1")
>>> diagram = Diagram([f, g, h, k, h1])
>>> grid = DiagramGrid(diagram)
>>> print(drawer.draw(diagram, grid))
\xymatrix{
A \ar[r]_{f} \ar@/^1cm/[rr]^{h_{1}} & B \ar[d]^{g} & D \ar[l]^{k} \ar@/_2cm/[ll]_{h} \\
& C &
}

The default value of default_curving_step is 4 units.

See also

draw, ArrowStringDescription

draw(diagram, grid, masked=None, diagram_format='')[source]

Returns the Xy-pic representation of diagram laid out in grid.

Consider the following simple triangle diagram.

>>> from ..categories import Object, NamedMorphism, Diagram
>>> from ..categories import DiagramGrid, XypicDiagramDrawer
>>> A = Object("A")
>>> B = Object("B")
>>> C = Object("C")
>>> f = NamedMorphism(A, B, "f")
>>> g = NamedMorphism(B, C, "g")
>>> diagram = Diagram([f, g], {g * f: "unique"})

To draw this diagram, its objects need to be laid out with a DiagramGrid:

>>> grid = DiagramGrid(diagram)

Finally, the drawing:

>>> drawer = XypicDiagramDrawer()
>>> print(drawer.draw(diagram, grid))
\xymatrix{
A \ar[d]_{g\circ f} \ar[r]^{f} & B \ar[ld]^{g} \\
C &
}

The argument masked can be used to skip morphisms in the presentation of the diagram:

>>> print(drawer.draw(diagram, grid, masked=[g * f]))
\xymatrix{
A \ar[r]^{f} & B \ar[ld]^{g} \\
C &
}

Finally, the diagram_format argument can be used to specify the format string of the diagram. For example, to increase the spacing by 1 cm, proceeding as follows:

>>> print(drawer.draw(diagram, grid, diagram_format="@+1cm"))
\xymatrix@+1cm{
A \ar[d]_{g\circ f} \ar[r]^{f} & B \ar[ld]^{g} \\
C &
}
modelparameters.sympy.categories.diagram_drawing.preview_diagram(diagram, masked=None, diagram_format='', groups=None, output='png', viewer=None, euler=True, **hints)[source]

Combines the functionality of xypic_draw_diagram and sympy.printing.preview. The arguments masked, diagram_format, groups, and hints are passed to xypic_draw_diagram, while output, viewer, and ``euler are passed to preview.

Examples

>>> from ..categories import Object, NamedMorphism, Diagram
>>> from ..categories import preview_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"})
>>> preview_diagram(d)

See also

xypic_diagram_drawer

modelparameters.sympy.categories.diagram_drawing.xypic_draw_diagram(diagram, masked=None, diagram_format='', groups=None, **hints)[source]

Provides a shortcut combining DiagramGrid and XypicDiagramDrawer. Returns an Xy-pic presentation of diagram. The argument masked is a list of morphisms which will be not be drawn. The argument diagram_format is the format string inserted after “xymatrix”. groups should be a set of logical groups. The hints will be passed directly to the constructor of DiagramGrid.

For more information about the arguments, see the docstrings of DiagramGrid and XypicDiagramDrawer.draw.

Examples

>>> from ..categories import Object, NamedMorphism, Diagram
>>> from ..categories import xypic_draw_diagram
>>> A = Object("A")
>>> B = Object("B")
>>> C = Object("C")
>>> f = NamedMorphism(A, B, "f")
>>> g = NamedMorphism(B, C, "g")
>>> diagram = Diagram([f, g], {g * f: "unique"})
>>> print(xypic_draw_diagram(diagram))
\xymatrix{
A \ar[d]_{g\circ f} \ar[r]^{f} & B \ar[ld]^{g} \\
C &
}

See also

XypicDiagramDrawer, DiagramGrid

Module contents

Category Theory module.

Provides some of the fundamental category-theory-related classes, including categories, morphisms, diagrams. Functors are not implemented yet.

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.

The latest version of this book should be available for free download from

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