DisCoPy documentation#

DisCoPy is a Python toolkit for computing with string diagrams.

Organisation: https://discopy.org
Documentation: https://docs.discopy.org
Source code: discopy/discopy
Paper (for applied category theorists): https://doi.org/10.4204/EPTCS.333.13
Paper (for quantum computer scientists): https://arxiv.org/abs/2205.05190

DisCoPy began as an implementation of DisCoCat and QNLP. This has now become its own library: lambeq.

Features#

an Arrow data structure for free dagger categories with formal sums, unary operators and symbolic variables from SymPy
a Diagram data structure for planar string diagrams in any (pre)monoidal category in the hierarchy of graphical languages (with braids, twists, spiders, etc.)
a Hypergraph data structure for string diagrams in hypergraph categories and its restrictions to symmetric, traced, compact and Markov categories
methods for diagram composition, drawing, rewriting and Functor evaluation into:
- Python code, i.e. wires as types and boxes as functions
- tensor networks, i.e. wires as dimensions and boxes as arrays from NumPy, PyTorch, TensorFlow, TensorNetwork and JAX
an implementation of categorical quantum mechanics interfacing with:
- tket for circuit compilation
- PyZX for optimisation with the ZX calculus
- PennyLane for automatic differentiation
an implementation of formal grammars (context-free, categorial, pregroup or dependency) with interfaces to lambeq, spaCy and NLTK

Example: Cooking#

This example is inspired from Pawel Sobocinski’s blog post Crema di Mascarpone and Diagrammatic Reasoning.

from discopy.symmetric import Ty as Ingredient, Box as Step, Diagram as Recipe

egg, white, yolk = Ingredient("egg"), Ingredient("white"), Ingredient("yolk")
crack = Step("crack", egg, white @ yolk)
merge = lambda x: Step("merge", x @ x, x)

# DisCoPy allows string diagrams to be defined as Python functions

@Recipe.from_callable(egg @ egg, white @ yolk)
def crack_two_eggs(left_egg, right_egg):
    left_white, left_yolk = crack(left_egg)
    right_white, right_yolk = crack(right_egg)
    return (merge(white)(left_white, right_white),
            merge(yolk)(left_yolk, right_yolk))

# ... or in point-free style using parallel (@) and sequential (>>) composition

assert crack_two_eggs == crack @ crack\
  >> white @ Recipe.swap(yolk, white) @ yolk\
  >> merge(white) @ merge(yolk)

crack_two_eggs.draw()

crack_two_eggs.draw()

Quickstart#

pip install discopy

If you want to see DisCoPy in action, check out the QNLP tutorial!

Contribute#

We’re keen to welcome new contributors!

First, read the contributing guidelines. Then get in touch on Discord or open an issue.

How to cite#

If you used DisCoPy in the context of an academic publication, we suggest you cite:

G. de Felice, A. Toumi & B. Coecke, DisCoPy: Monoidal Categories in Python, EPTCS 333, 2021, pp. 183-197, DOI: 10.4204/EPTCS.333.13

If furthermore your work is related to quantum computing, you can also cite:

A. Toumi, G. de Felice & R. Yeung, DisCoPy for the quantum computer scientist, arXiv:2205.05190

If you use any of the recent features (e.g. Hypergraph) you should also mention:

A. Toumi, R. Yeung, B. Poór & G. de Felice, DisCoPy: the Hierarchy of Graphical Languages in Python arXiv:2311.10608

Architecture#

Software dependencies between modules go top-to-bottom, left-to-right and forgetful functors between categories go the other way.

syntax
	cat │		grammar
┌─────── │	monoidal │	───────┐ │	cfg
braided │ │ │ │ │ │ │	traced │ │ │ │ │ └──────	closed │	categorial
		rigid │	pregroup
		pivotal │	dependency
		pivotal │
balanced │	───────────── interaction	ribbon │	circuit
symmetric │	───────────── hypergraph	compact │	tk
markov	─────────────	frobenius	zx

python	matrix	tensor	channel
semantics			quantum

DisCoPy documentation

Contents