Discopy: Categorical Computing with String Diagrams

When to Use This Skill

Use Discopy when you need:

• Compositional Systems: Building modular systems with formal composition guarantees
• Quantum NLP (QNLP): Converting natural language to quantum circuits via categorical semantics
• Diagrammatic Reasoning: Visual representation of computational flows with mathematical rigor
• Tensor Network Computation: Abstract tensor operations with multiple backend support
• Categorical Quantum Mechanics: Designing and optimizing quantum circuits categorically
• Research Prototyping: Rapid experimentation with compositional models
• Category Theory Education: Executable mathematical concepts with visualization

Sweet Spot: Research at the mathematics-computer science interface, QNLP experiments, compositional semantics modeling, and educational tools for category theory.

Not For: Production NLP systems (use spaCy/Transformers), large-scale quantum compilation (use Qiskit/Cirq), or standard ML pipelines (use PyTorch/scikit-learn).

Core Concepts

The Big Picture: Information Plumbing

Discopy treats computation as information flow through typed channels:

• Wires = Types (information channels)
• Boxes = Operations (transformations)
• Diagrams = Compositions (pipelines)
• Functors = Interpretations (semantics)

Text → Parse → Diagram → Functor → Tensor/Circuit → Evaluate → Result

Category Hierarchy

Category (objects + morphisms)
  ↓
Monoidal (>> sequential, @ parallel)
  ↓
Symmetric (swap wires)
  ↓
Rigid (duals)
  ↓
Compact (cups/caps)
  ↓
Traced (feedback loops)

Each level adds capabilities while maintaining composition guarantees.

Key Operations

# Sequential composition (then)
f >> g  # "f then g"

# Parallel composition (and)
f @ g   # "f and g simultaneously"

# Dagger (adjoint/inverse)
f.dagger()

# Tensor product
f.tensor(g)

# Feedback
f.feedback()

Quick Start

Installation

# Basic installation
pip install discopy

# With quantum features
pip install discopy[quantum]

# With all backends
pip install discopy[pytorch,tensorflow,jax]

Hello World: Simple Composition

from discopy import Ty, Box

# Define types (objects)
x = Ty('X')
y = Ty('Y')
z = Ty('Z')

# Define operations (morphisms)
f = Box('f', x, y)  # f: X → Y
g = Box('g', y, z)  # g: Y → Z

# Sequential composition
diagram = f >> g  # X → Y → Z

# Parallel composition
parallel = f @ g  # X⊗Y → Y⊗Z

# Visualize
diagram.draw()

Tensor Evaluation

from discopy.matrix import Functor
import numpy as np

# Define semantics
F = Functor(
    ob={x: 2, y: 3, z: 4},  # Dimensions
    ar={
        f: np.random.rand(3, 2),  # Y=3, X=2
        g: np.random.rand(4, 3)   # Z=4, Y=3
    }
)

# Evaluate
result = F(diagram)
print(result.array.shape)  # (4, 2)

Quantum Circuit

from discopy.quantum.circuit import Circuit, gates

# Build circuit
circuit = (
    gates.H @ Circuit.id(1)  # Hadamard on qubit 0
    >> gates.CNOT            # CNOT on qubits 0,1
    >> gates.Rx(0.5) @ gates.Ry(0.3)  # Rotations
)

# Visualize
circuit.draw()

# Export to other frameworks
qiskit_circuit = circuit.to_qiskit()

Progressive Disclosure: 7-Level Framework

DisCoPy follows a 7-level progression from simple pipelines to formally verified systems.

Level 1: Novice - Sequential Composition

→ EXAMPLES-L1-L2.md - Basic >> pipelines

• Core: Chain operations sequentially
• Use Cases: ETL, image preprocessing, API chains
• Examples: 5 complete implementations with diagrams

Level 2: Competent - Parallel Composition + Functors

→ EXAMPLES-L1-L2.md - Parallel @ + evaluation

• Core: Parallel operations, concrete tensor evaluation
• Use Cases: Ensemble ML, feature extraction, backend selection
• Examples: 7 complete implementations with NumPy/PyTorch

Level 3: Proficient - Symmetric Monoidal (Wire Swapping)

→ EXAMPLES-L3-L4.md - Diagram.swap() for routing

• Core: Type-aware composition, argument reordering
• Use Cases: Microservices routing, flexible composition
• Examples: 5 complete implementations with braiding

Level 4: Advanced - Compact Closed (Quantum)

→ EXAMPLES-L3-L4.md - Cups, caps, quantum circuits

• Core: Duality, entanglement, QNLP
• Use Cases: Quantum computing, quantum NLP
• Examples: 7 complete quantum circuit implementations

Level 5: Expert - Traced Monoidal (Feedback Loops)

→ EXAMPLES-L5-L7.md - .trace() for state feedback

• Core: RNNs, iterative algorithms, stateful workflows
• Use Cases: LSTMs, RL agents, game loops
• Examples: 5 complete implementations with traced categories

Level 6: Master - Custom Functors & Multi-Backend

→ EXAMPLES-L5-L7.md - GPU acceleration, custom semantics

• Core: Backend selection (NumPy/PyTorch/JAX), custom functor logic
• Use Cases: Production ML, GPU inference, A/B testing
• Examples: 5 complete implementations with benchmarks

Level 7: Genius - Formal Verification

→ EXAMPLES-L5-L7.md - Proof-carrying code

• Core: Runtime assertions, type-level proofs, Coq verification
• Use Cases: Safety-critical, medical devices, smart contracts
• Examples: 4 complete implementations with proofs

Real-World Applications

→ USE-CASES.md - Complete use cases across all levels

• ETL pipelines, ML ensembles, quantum computing
• RNNs/LSTMs, production ML, verified systems
• Decision tree for level selection

Common Patterns

Pattern 1: Build-Interpret-Evaluate

# 1. Build diagram (syntax)
diagram = f >> g >> h

# 2. Define functor (semantics)
functor = Functor(ob={...}, ar={...})

# 3. Evaluate
result = functor(diagram)

Pattern 2: Grammar to Circuit

# 1. Parse text
from discopy.grammar.pregroup import Diagram as Grammar

sentence = parse("Alice loves Bob")

# 2. Convert to quantum
from discopy.quantum.circuit import Functor as CircuitFunctor

to_circuit = CircuitFunctor(word_circuits, grammar_ops)
circuit = to_circuit(sentence)

# 3. Execute
result = circuit.eval()

Pattern 3: Custom Domain Functor

class DomainFunctor(Functor):
    def __init__(self, domain_mappings):
        self.mappings = domain_mappings

    def __call__(self, diagram):
        # Custom interpretation logic
        return self.interpret(diagram)

API Quick Reference

→ REFERENCE.md - Complete API lookup

Best Practices

→ PATTERNS.md - Design patterns and idioms

Troubleshooting

→ TROUBLESHOOTING.md - Common issues and solutions

Integration Guide

→ INTEGRATION.md - Using Discopy with other libraries

Learning Path

1. Start Here: Run examples in EXAMPLES.md
2. Understand Types: Read about Ty and type composition
3. Master Functors: Learn evaluation patterns
4. Build Circuits: Explore quantum module
5. Try QNLP: Complete pipeline example
6. Create Custom: Implement domain-specific functors
7. Optimize: Learn tensor backend selection

When NOT to Use Discopy

❌ Production NLP: Use spaCy, Transformers (Discopy is research-focused) ❌ Large Quantum Circuits: Use Qiskit, Cirq (better optimization) ❌ Standard Deep Learning: Use PyTorch, TensorFlow directly ❌ High-Performance Numerics: Use NumPy, SciPy (less overhead) ❌ Commercial Applications: Wait for hardware maturity (QNLP still experimental)

Philosophy: Composition Over Decomposition

Discopy inverts traditional programming:

• Traditional: Break problems down into parts
• Compositional: Build solutions from composable pieces

The categorical approach provides:

• Formal Guarantees: Composition laws ensure correctness
• Visual Reasoning: Diagrams make structure explicit
• Backend Flexibility: Same diagram, multiple interpretations
• Mathematical Rigor: Proofs about correctness possible

Resources

• Documentation: https://docs.discopy.org
• Paper: "DisCoPy: Monoidal Categories in Python" (ACT 2021)
• Tutorials: EXAMPLES.md in this skill
• API Reference: REFERENCE.md
• Integration: INTEGRATION.md

Next Steps

1. Install: pip install discopy
2. Run: Examples in EXAMPLES.md
3. Explore: Modify examples for your domain
4. Build: Create custom functors
5. Share: Contribute back to community