diagrams.Diagram

class rewalt.diagrams.Diagram(ambient)

Bases: object

Class for diagrams, that is, mappings from a shape to an “ambient” diagrammatic set.

To create a diagram, we start from generators of a diagrammatic set, returned by the DiagSet.add() method or requested with indexer operators.

Then we produce other diagrams in two main ways:

pulling back a diagram along a map of shapes (pullback()), or
pasting together two diagrams along their boundaries (paste(), to_inputs(), to_outputs()).

In practice, the direct use of pullback(), which requires an explicit shape map, can be avoided in common cases by using unit(), lunitor(), runitor(), or the specialised SimplexDiagram.simplex_degeneracy, CubeDiagram.cube_degeneracy, and CubeDiagram.cube_connection methods.

Notes

Initialising a Diagram directly creates an empty diagram in a given diagrammatic set.

Parameters: ambient (DiagSet) – The ambient diagrammatic set.

Methods

`boundary`(sign[, dim])	Returns the boundary of a given orientation and dimension.
`draw`(**params)	Bound version of `strdiags.draw()`.
`draw_boundaries`(**params)	Bound version of `strdiags.draw_boundaries()`.
`generate_layering`()	Assigns a layering to the diagram, iterating through all the layerings, and returns it.
`hasse`(**params)	Bound version of `hasse.draw()`.
`lunitor`([sign, positions])	Returns a left unitor on the diagram: a degenerate diagram one dimension higher, with one boundary equal to the diagram, and the other equal to the diagram with units pasted to some of its inputs.
`paste`(other[, dim])	Given two diagrams and `k` such that the output `k`-boundary of the first is equal to the input `k`-boundary of the second, returns their pasting along the matching boundaries.
`pullback`(shapemap[, name])	Returns the pullback of the diagram along a shape map.
`rename`(name)	Renames the diagram.
`rewrite`(positions, diagram)	Returns the diagram representing the application of a higher-dimensional rewrite to a subdiagram, specified by the positions of its top-dimensional elements.
`runitor`([sign, positions])	Returns a right unitor on the diagram: a degenerate diagram one dimension higher, with one boundary equal to the diagram, and the other equal to the diagram with units pasted to some of its outputs.
`to_inputs`(positions, other[, dim])	Returns the pasting of another diagram along a round subshape of the input `k`-boundary, specified by the positions of its `k`-dimensional elements.
`to_outputs`(positions, other[, dim])	Returns the pasting of another diagram along a round subshape of the output `k`-boundary, specified by the positions of its `k`-dimensional elements.
`unit`()	Returns the unit on the diagram: a degenerate diagram one dimension higher, with input and output equal to the diagram.
`with_layers`(fst, *layers)	Given a non-zero number of diagrams that can be pasted sequentially in the top dimension, returns their pasting.
`yoneda`(shapemap[, name])	Alternative constructor creating a diagram from a `shapes.ShapeMap`.

Attributes

`ambient`	Returns the ambient diagrammatic set.
`composite`	Returns the composite of the diagram, if it exists.
`compositor`	Returns the compositor of the diagram, if it exists.
`dim`	Shorthand for `shape.dim`.
`hascomposite`	Returns whether the diagram has a composite.
`input`	Alias for `boundary('-')`.
`inverse`	Returns the inverse of an invertible cell.
`iscell`	Shorthand for `shape.isatom` (a cell is a diagram whose shape is an atom).
`isdegenerate`	Returns whether the diagram is degenerate, that is, its image has dimension strictly lower than the dimension of its shape.
`isinvertiblecell`	Returns whether the diagram is an invertible cell.
`isround`	Shorthand for `shape.isround`.
`layers`	Returns the layering of the diagram corresponding to the current layering of the shape.
`linvertor`	Returns the left invertor for an invertible cell.
`mapping`	Returns the data specifying the mapping of shape elements to generators.
`name`	Returns the name of the diagram.
`output`	Alias for `boundary('+')`.
`rewrite_steps`	Returns the sequence of rewrite steps associated to the current layering of the diagram.
`rinvertor`	Returns the right invertor for an invertible cell.
`shape`	Returns the shape of the diagram.

property name

Returns the name of the diagram.

Returns: name – The name of the diagram.
Return type: hashable

property shape

Returns the shape of the diagram.

Returns: shape – The shape of the diagram.
Return type: shapes.Shape

property ambient

Returns the ambient diagrammatic set.

Returns: ambient – The ambient diagrammatic set.
Return type: DiagSet

property mapping

Returns the data specifying the mapping of shape elements to generators.

The mapping is specified as a list of lists, similar to ogposets.OgMap, in the following way: mapping[n][k] == s if the diagram sends El(n, k) to the generator named s.

Returns: mapping – The data specifying the diagram’s assignment.
Return type: list[list[hashable]]

property layers

Returns the layering of the diagram corresponding to the current layering of the shape.

Returns: layers – The current layering.
Return type: list[Diagram]

property rewrite_steps

Returns the sequence of rewrite steps associated to the current layering of the diagram.

The 0-th rewrite step is the input boundary of the diagram. For n > 0, the n-th rewrite step is the output boundary of the (n-1)-th layer.

Returns: rewrite_steps – The current sequence of rewrite steps.
Return type: list[Diagram]

property dim: Shorthand for shape.dim.

property isdegenerate

Returns whether the diagram is degenerate, that is, its image has dimension strictly lower than the dimension of its shape.

Returns: isdegenerate – True if and only if the diagram is degenerate.
Return type: bool

property isround: Shorthand for shape.isround.

property iscell: Shorthand for shape.isatom (a cell is a diagram whose shape is an atom).

property isinvertiblecell

Returns whether the diagram is an invertible cell.

A cell is invertible if either

it is degenerate, or
its image is an invertible generator.

Returns: isinvertiblecell – True if and only if the diagram is an invertible cell.
Return type: bool

property hascomposite

Returns whether the diagram has a composite.

Returns: hascomposite – True if and only if the diagram has a composite.
Return type: bool

rename(name)

Renames the diagram.

Parameters: name (hashable) – The new name for the diagram.

paste(other, dim=None, **params)

Given two diagrams and k such that the output k-boundary of the first is equal to the input k-boundary of the second, returns their pasting along the matching boundaries.

Parameters

fst (Diagram) – The first diagram.
snd (Diagram) – The second diagram.
dim (int, optional) – The dimension of the boundary along which they will be pasted (default is min(fst.dim, snd.dim) - 1).

Keyword Arguments

cospan (bool) – Whether to also return the cospan of inclusions of the two diagrams’ shapes into the pasting (default is False).

Returns

paste (Diagram) – The pasted diagram.
paste_cospan (ogposets.OgMapPair, optional) – The cospan of inclusions of the two diagrams’ shapes into their pasting.

Raises

ValueError – If the boundaries do not match.

to_outputs(positions, other, dim=None, **params)

Returns the pasting of another diagram along a round subshape of the output k-boundary, specified by the positions of its k-dimensional elements.

Parameters

positions (list[int] | int) – The positions of the outputs along which to paste. If given an integer n, interprets it as the list [n].
other (Diagram) – The other diagram to paste.
dim (int, optional) – The dimension of the boundary along which to paste (default is self.dim - 1)

Keyword Arguments

cospan (bool) – Whether to return the cospan of inclusions of the two diagrams’ shapes into the pasting (default is False).

Returns

to_outputs (Shape) – The pasted diagram.
paste_cospan (ogposets.OgMapPair, optional) – The cospan of inclusions of the two diagrams’ shapes into their pasting.

Raises

ValueError – If the boundaries do not match, or the pasting does not produce a well-formed shape.

to_inputs(positions, other, dim=None, **params)

Returns the pasting of another diagram along a round subshape of the input k-boundary, specified by the positions of its k-dimensional elements.

Parameters

positions (list[int] | int) – The positions of the inputs along which to paste. If given an integer n, interprets it as the list [n].
other (Diagram) – The other diagram to paste.
dim (int, optional) – The dimension of the boundary along which to paste (default is self.dim - 1)

Keyword Arguments

cospan (bool) – Whether to return the cospan of inclusions of the two diagrams’ shapes into the pasting (default is False).

Returns

to_inputs (Shape) – The pasted diagram.
paste_cospan (ogposets.OgMapPair, optional) – The cospan of inclusions of the two diagrams’ shapes into their pasting.

Raises

ValueError – If the boundaries do not match, or the pasting does not produce a well-formed shape.

rewrite(positions, diagram)

Returns the diagram representing the application of a higher-dimensional rewrite to a subdiagram, specified by the positions of its top-dimensional elements.

This is in fact an alias for to_outputs() in the top dimension, reflecting the intuitions of higher-dimensional rewriting in this situation.

Parameters

positions (list[int] | int) – The positions of the top-dimensional elements to rewrite. If given an integer n, interprets it as the list [n].
diagram (Diagram) – The diagram representing the rewrite to apply.

Returns

rewrite – The diagram representing the application of the rewrite to the given positions.

Return type

Shape

pullback(shapemap, name=None)

Returns the pullback of the diagram along a shape map.

Parameters

shapemap (shapes.ShapeMap) – The map along which to pull back.
name (hashable, optional) – The name to give to the new diagram.

Returns

pullback – The pulled back diagram.

Return type

Diagram

Raises

ValueError – If the target of the map is not equal to the diagram shape.

boundary(sign, dim=None)

Returns the boundary of a given orientation and dimension.

This is, by definition, the pullback of a diagram along the inclusion map self.shape.boundary(sign, dim).

Parameters

sign (str) – Orientation: '-' for input, '+' for output.
dim (int, optional) – Dimension of the boundary (default is self.dim - 1).

Returns

boundary – The requested boundary.

Return type

Diagram

property input: Alias for boundary('-').

property output: Alias for boundary('+').

unit()

Returns the unit on the diagram: a degenerate diagram one dimension higher, with input and output equal to the diagram.

This is, by definition, the pullback of the diagram along self.shape.inflate().

Returns: unit – The unit diagram.
Return type: Diagram

lunitor(sign='-', positions=None)

Returns a left unitor on the diagram: a degenerate diagram one dimension higher, with one boundary equal to the diagram, and the other equal to the diagram with units pasted to some of its inputs.

Parameters

sign (str, optional) – The boundary on which the units are: '-' (default) for input, '+' for output.
positions (list[int] | int) – The positions of the inputs to which a unit is attached (default is all of the inputs). If given an integer n, interprets it as the list [n].

Returns

lunitor – The left unitor diagram.

Return type

Diagram

Raises

ValueError – If the positions do not correspond to inputs.

runitor(sign='-', positions=None)

Returns a right unitor on the diagram: a degenerate diagram one dimension higher, with one boundary equal to the diagram, and the other equal to the diagram with units pasted to some of its outputs.

Parameters

sign (str, optional) – The boundary on which the units are: '-' (default) for input, '+' for output.
positions (list[int] | int) – The positions of the outputs to which a unit is attached (default is all of the outputs). If given an integer n, interprets it as the list [n].

Returns

runitor – The right unitor diagram.

Return type

Diagram

Raises

ValueError – If the positions do not correspond to outputs.

property inverse

Returns the inverse of an invertible cell.

Returns: inverse – The inverse cell.
Return type: Diagram
Raises: ValueError – If the diagram is not an invertible cell.

property rinvertor

Returns the right invertor for an invertible cell.

Returns: rinvertor – The right invertor.
Return type: Diagram
Raises: ValueError – If the diagram is not an invertible cell.

property linvertor

Returns the left invertor for an invertible cell.

Returns: linvertor – The left invertor.
Return type: Diagram
Raises: ValueError – If the diagram is not an invertible cell.

property composite

Returns the composite of the diagram, if it exists.

Returns: composite – The composite.
Return type: Diagram
Raises: ValueError – If the diagram does not have a composite.

property compositor

Returns the compositor of the diagram, if it exists.

Returns: compositor – The compositor.
Return type: Diagram
Raises: ValueError – If the diagram does not have a composite.

generate_layering()

Assigns a layering to the diagram, iterating through all the layerings, and returns it.

Returns: layers – The generated layering.
Return type: list[Diagram]

hasse(**params)

Bound version of hasse.draw().

Calling x.hasse(**params) is equivalent to calling hasse.draw(x, **params).

draw(**params)

Bound version of strdiags.draw().

Calling x.draw(**params) is equivalent to calling strdiags.draw(x, **params).

draw_boundaries(**params)

Bound version of strdiags.draw_boundaries().

Calling x.draw_boundaries(**params) is equivalent to calling strdiags.draw_boundaries(x, **params).

static yoneda(shapemap, name=None)

Alternative constructor creating a diagram from a shapes.ShapeMap.

Mathematically, diagrammatic sets are certain sheaves on the category of shapes and maps of shapes; this constructor implements the Yoneda embedding of a map of shapes.

Parameters

shapemap (shapes.Shape) – A map of shapes.
name (hashable, optional) – The name of the generated diagram.

Returns

yoneda – The Yoneda-embedded map.

Return type

Diagram

static with_layers(fst, *layers)

Given a non-zero number of diagrams that can be pasted sequentially in the top dimension, returns their pasting.

Parameters

fst (Diagram) – The first diagram.
*layers (Diagram) – Any number of additional diagrams.

Returns

with_layers – The pasting of all the diagrams in the top dimension.

Return type

Diagram

Raises

ValueError – If the diagrams are not pastable.