diagrams.DiagSet

class rewalt.diagrams.DiagSet

Bases: object

Class for diagrammatic sets, a model of higher-dimensional rewrite systems and/or directed cell complexes.

A diagrammatic set is constructed by creating an empty object, then adding named generators of different dimensions. The addition of a generator models the gluing of an atomic shapes.Shape object along its boundary.

This operation produces a diagram, that is, a map from a shape to the diagrammatic set, modelled as a Diagram object. From these “basic” diagrams, we can construct “derived” diagrams either by pasting, or by pulling back along shape maps (this is used to produce “unit” or “degenerate” diagrams).

To add a 0-dimensional generator (a point), we just give it a name. In the main constructor add(), the gluing of an n-dimensional generator is specified by a pair of round, (n-1)-dimensional Diagram objects, describing the gluing maps for the input and output boundaries of a shape.

Simplicial sets, cubical sets with connections, and reflexive globular sets are all special cases of diagrammatic sets, where the generators have simplicial, cubical, or globular shapes. There are special constructors add_simplex() and add_cube() for adding simplicial and cubical generators by listing all their faces.

The generators of a diagrammatic set are, by default, “directed” and not invertible. The class supports a model of weak or pseudo- invertibility, where two generators being each other’s “weak inverse” is witnessed by a pair of higher-dimensional generators (invertors). This is produced by the methods invert() (creates an inverse) and make_inverses() (makes an existing generator the inverse).

Diagrammatic sets do not have an intrinsic notion of composition of diagrams, so they are not by themselves a model of higher categories. However, the class supports a model of higher categories in which one generator being the composite of a diagram is witnessed by a higher-dimensional generator (a compositor). This is produced by the methods compose() (creates a composite) and make_composite() (makes an existing generator the composite).

Notes

There is an alternative constructor yoneda() which turns a shapes.Shape object into a diagrammatic set with one generator for every face of the shape.

Methods

`add`(name[, input, output])	Adds a generator and returns the diagram that maps the new generator into the diagrammatic set.
`add_cube`(name, faces, *kwargs)	Variant of `add()` for cube-shaped generators.
`add_simplex`(name, faces, *kwargs)	Variant of `add()` for simplex-shaped generators.
`compose`(diagram[, name, compositorname])	Given a round diagram, adds a weak composite for it, together with a compositor witnessing the composition, and returns them as diagrams.
`copy`()	Returns a copy of the object.
`invert`(generatorname[, inversename, ...])	Adds a weak inverse for a generator, together with left and right invertors that witness the inversion, and returns them as diagrams.
`make_composite`(generatorname, diagram[, ...])	Given a generator and a round diagram, it makes the first the weak composite of the second by adding a compositor, and returns the compositor as a diagram.
`make_inverses`(generatorname1, generatorname2)	Makes two generators each other's weak inverse by adding invertors, and returns the invertors.
`remove`(generatorname)	Removes a generator, together with all other generators that depend on it.
`update`(generatorname, **kwargs)	Updates the optional arguments of a generator.
`yoneda`(shape)	Alternative constructor creating a diagrammatic set from a `shapes.Shape`.

Attributes

`by_dim`	Returns the set of generators indexed by dimension.
`compositors`	Returns a dictionary of diagrams that have a non-trivial composite, indexed by their compositor's name.
`dim`	Returns the maximal dimension of a generator.
`generators`	Returns the object's internal representation of the set of generators and related data.
`iscubical`	Returns whether the diagrammatic sets is cubical, that is, all its generators are cube-shaped.
`issimplicial`	Returns whether the diagrammatic sets is simplicial, that is, all its generators are simplex-shaped.

property generators

Returns the object’s internal representation of the set of generators and related data.

This is a dictionary whose keys are the generators’ names. For each generator, the object stores another dictionary, which contains at least

the generator’s shape (shape, shapes.Shape),
the mapping of the shape (mapping, list[list[hashable]]),
the generator’s set of “faces”, that is, other generators appearing as codimension-1 faces of the generator (faces, set[hashable]),
the generator’s set of “cofaces”, that is, other generators that have the generator as a face (cofaces, set[hashable]).

If the generator has been inverted, it will also contain

its inverse’s name (inverse, hashable),
the left invertor’s name (linvertor, hashable),
the right invertor’s name (rinvertor, hashable).

If the generator happens to be a compositor, it will also contain the name of the composite it is exhibiting (composite, hashable).

This also stores any additional keyword arguments passed when adding the generator.

Returns: generators – The generators data.
Return type: dict[dict]

property by_dim

Returns the set of generators indexed by dimension.

Returns: by_dim – The set of generators indexed by dimension.
Return type: dict[hashable]

property compositors

Returns a dictionary of diagrams that have a non-trivial composite, indexed by their compositor’s name.

More precisely, rather than Diagram objects, the dictionary stores the shape and mapping data that allows to reconstruct them.

Returns: compositors – The dictionary of composed diagrams.
Return type: dict[dict]

property dim

Returns the maximal dimension of a generator.

Returns: dim – The maximal dimension of a generator, or -1 if empty.
Return type: int

property issimplicial

Returns whether the diagrammatic sets is simplicial, that is, all its generators are simplex-shaped.

Returns: issimplicial – True if and only if the shape of every generator is a shapes.Simplex object.
Return type: bool

property iscubical

Returns whether the diagrammatic sets is cubical, that is, all its generators are cube-shaped.

Returns: iscubical – True if and only if the shape of every generator is a shapes.Cube object.
Return type: bool

add(name, input=None, output=None, **kwargs)

Adds a generator and returns the diagram that maps the new generator into the diagrammatic set.

The gluing of the generator is specified by a pair of round diagrams with identical boundaries, corresponding to the input and output diagrams of the new generator. If none are given, adds a point (0-dimensional generator).

Parameters

name (hashable) – Name to assign to the new generator.
input (Diagram, optional) – The input diagram of the new generator (default is None)
output (Diagram, optional) – The output diagram of the new generator (default is None)

Keyword Arguments

color (multiple types) – Fill color when pictured as a node in string diagrams. If stroke is not specified, this is also the color when pictured as a wire.
stroke (multiple types) – Stroke color when pictured as a node, and color when pictured as a wire.
draw_node (bool) – If False, no node is drawn when picturing the generator in string diagrams.
draw_label (bool) – If False, no label is drawn when picturing the generator in string diagrams.

Returns

generator – The diagram picking the new generator.

Return type

Diagram

Raises

ValueError – If the name is already in use, or the input and output diagrams do not have round and matching boundaries.

add_simplex(name, *faces, **kwargs)

Variant of add() for simplex-shaped generators.

The gluing of the generator is specified by a number of SimplexDiagram objects, corresponding to the faces of the new generator as listed by SimplexDiagram.simplex_face.

Parameters

name (hashable) – Name to assign to the new generator.
*faces (SimplexDiagram) – The simplicial faces of the new generator.

Keyword Arguments

**kwargs – Same as add().

Returns

generator – The diagram picking the new generator.

Return type

SimplexDiagram

Raises

ValueError – If the name is already in use, or the faces do not have matching boundaries.

add_cube(name, *faces, **kwargs)

Variant of add() for cube-shaped generators.

The gluing of the generator is specified by a number of CubeDiagram objects, corresponding to the faces of the new generator as listed by CubeDiagram.cube_face, in the order (0, '-'), (0, '+'), (1, '-'), (1, '+'), etc.

Parameters

name (hashable) – Name to assign to the new generator.
*faces (CubeDiagram) – The cubical faces of the new generator.

Keyword Arguments

**kwargs – Same as add().

Returns

generator – The diagram picking the new generator.

Return type

CubeDiagram

Raises

ValueError – If the name is already in use, or the faces do not have matching boundaries.

invert(generatorname, inversename=None, rinvertorname=None, linvertorname=None, **kwargs)

Adds a weak inverse for a generator, together with left and right invertors that witness the inversion, and returns them as diagrams.

Both the inverse and the invertors can be given custom names. If the generator to be inverted is named 'a', the default names are

'a⁻¹' for the inverse,
'inv(a, a⁻¹)' for the right invertor,
'inv(a⁻¹, a)' for the left invertor.

In the theory of diagrammatic sets, weak invertibility would correspond to the situation where the invertors themselves are weakly invertible, coinductively. In the implementation, we take an “invert when necessary” approach, where invertors are not invertible by default, and should be inverted when needed.

Notes

The right invertor for the generator is the left invertor for its inverse, and the left invertor for the generator is the right invertor for its inverse.

Parameters

generatorname (hashable) – Name of the generator to invert.
inversename (hashable, optional) – Name assigned to the inverse.
rinvertorname (hashable, optional) – Name assigned to the right invertor.
linvertorname (hashable, optional) – Name assigned to the left invertor.

Keyword Arguments

**kwargs – Passed to add() when adding the inverse.

Returns

inverse (Diagram) – The diagram picking the inverse.
rinvertor (Diagram) – The diagram picking the right invertor.
linvertor (Diagram) – The diagram picking the left invertor.

Raises

ValueError – If the generator is already inverted, or 0-dimensional.

make_inverses(generatorname1, generatorname2, rinvertorname=None, linvertorname=None)

Makes two generators each other’s weak inverse by adding invertors, and returns the invertors.

In what follows, “right/left” invertors are relative to the first generator. Both invertors can be given custom names. If the generators are named 'a', 'b', the default names for the invertors are

'inv(a, b)' for the right invertor,
'inv(b, a)' for the left invertor.

In the theory of diagrammatic sets, weak invertibility would correspond to the situation where the invertors themselves are weakly invertible, coinductively. In the implementation, we take an “invert when necessary” approach, where invertors are not invertible by default, and should be inverted when needed.

Parameters

generatorname1 (hashable) – Name of the first generator.
generatorname2 (hashable, optional) – Name of the second generator.
rinvertorname (hashable, optional) – Name assigned to the right invertor.
linvertorname (hashable, optional) – Name assigned to the left invertor.

Returns

rinvertor (Diagram) – The diagram picking the right invertor.
linvertor (Diagram) – The diagram picking the left invertor.

Raises

ValueError – If the generators are already inverted, or 0-dimensional, or do not have compatible boundaries.

compose(diagram, name=None, compositorname=None, **kwargs)

Given a round diagram, adds a weak composite for it, together with a compositor witnessing the composition, and returns them as diagrams.

Both the composite and the compositor can be given custom names. If the diagram to be composed is named 'a', the default names are

'⟨a⟩' for the composite,
'comp(a)' for the compositor.

In the theory of diagrammatic sets, a weak composite is witnessed by a weakly invertible compositor. In the implementation, we take an “invert when necessary” approach, where compositors are not invertible by default, and should be inverted when needed.

Notes

A cell (a diagram whose shape is an atom) is treated as already having itself as a composite, witnessed by a unit cell; this method can only be used on non-atomic diagrams.

Parameters

diagram (Diagram) – The diagram to compose.
name (hashable, optional) – Name of the weak composite.
compositorname (hashable, optional) – Name of the compositor.

Keyword Arguments

**kwargs – Passed to add() when adding the composite.

Returns

composite (Diagram) – The diagram picking the composite.
compositor (Diagram) – The diagram picking the compositor.

Raises

ValueError – If the diagram is not round, or already has a composite.

make_composite(generatorname, diagram, compositorname=None)

Given a generator and a round diagram, it makes the first the weak composite of the second by adding a compositor, and returns the compositor as a diagram.

The compositor can be given a custom name. If the diagram to be composed is named 'a', the default name is 'comp(a)'.

In the theory of diagrammatic sets, a weak composite is witnessed by a weakly invertible compositor. In the implementation, we take an “invert when necessary” approach, where compositors are not invertible by default, and should be inverted when needed.

Notes

A cell (a diagram whose shape is an atom) is treated as already having itself as a composite, witnessed by a unit cell; this method can only be used on non-atomic diagrams.

Parameters

generatorname (hashable) – Name of the generator that should be its composite.
diagram (Diagram) – The diagram to compose.
compositorname (hashable, optional) – Name of the compositor.

Returns

compositor – The diagram picking the compositor.

Return type

Diagram

Raises

ValueError – If the diagram is not round, or already has a composite, or the diagram and the generator do not have matching boundaries.

remove(generatorname)

Removes a generator, together with all other generators that depend on it.

Parameters: generatorname (hashable) – Name of the generator to remove.

update(generatorname, **kwargs)

Updates the optional arguments of a generator.

Parameters: generatorname (hashable) – Name of the generator to update.
Keyword Arguments: **kwargs – Any arguments to update.
Raises: AttributeError – If the optional argument uses a private keyword.

copy()

Returns a copy of the object.

Returns: copy – A copy of the object.
Return type: DiagSet

static yoneda(shape)

Alternative constructor creating a diagrammatic set from a shapes.Shape.

Mathematically, diagrammatic sets are certain sheaves on the category of shapes and maps of shapes; this constructor implements the Yoneda embedding of a shape. This has an n-dimensional generator for each n-dimensional element of the shape.

Parameters: shape (shapes.Shape) – A shape.
Returns: yoneda – The Yoneda-embedded shape.
Return type: DiagSet