What is a channel? — an introductory notebook for the documentation

[giodefelice-agents]

Let's write a new PR in optyx with a notebook describing all the features that are coming up with the other PRs. The idea is to write an introduction to photonics hardware and how to simulate it in optyx, it will be the first notebook in the documentation, or could even be used in the readme. Title: "What is a channel?" [structure 1–9, verbatim in TODO.md]

Adds docs/notebooks/what_is_a_channel.ipynb, executed end to end (~20 s), as the first entry of docs/notebooks.rst, with a CI step executing it like the fixpoints notebook.

Structure — the nine sections requested, each with a drawn diagram and a simulation:

1. Gates — BS, Phase, MZI, the ansatz interferometer, and an arbitrary unitary via Gate (3-mode Fourier), with to_path() recovering the matrix.
2. States — Create Fock states (HOM amplitudes), dual rail via DualRail and to_dual_rail (GHZ).
3. Effects — Select amplitudes, observables via from_bosonic_operator (number operator, and a formal sum for total photon number conserved by BS).
4. Noise — PhotonLoss as a discarded environment, the Stinespring picture, double() drawn as an Equation, lossy HOM.
5. Distinguishability — internal_states + inflate, the HOM dip at overlap $1/\sqrt 2$ giving coincidence $1/4$.
6. Measurement — classical wires, state >> unitary >> measure boson sampling on the Fourier interferometer.
7. Classical control — ClassicalFunction + BitControlledGate: one gate measured, the other controlled.
8. Feedback — feedback(mem=..., state=...), unroll, at_time trajectory, eigen_fix fixed point (the MZI loop).
9. The universal setup — a UniversalSetup(Diagram) class: state ψ into a classically controlled isometry from M+L to M+L+E with C control bits, E discarded (PhotonLoss), L qmode feedback loops, M outputs measured via Measure(qmode), feedforward into X+C with the C bits fed back as control. Drawn (draw + unroll(1)) and simulated: at_time trajectory converges to the value both eigen_fix and fix agree on.

Stacking — based on claude/optyx-pr15-review-plan-cb0p1g (PR #26), since sections 8–9 use the feedback/fixpoint surface of PRs #12 → #15 → #26; the diff is the notebook, the docs index, the CI step and TODO.md.

Found along the way — a multi-wire Discard cannot be drawn (KeyError in discopy's draw_discard), filed as #35; the notebook works around it by passing the feedback effect as a tensor of single-wire discards.

Checks — notebook executes cleanly from scratch; pflake8 optyx clean (no source changes); full pytest run reported on the thread once finished.

🤖 Generated with Claude Code

https://claude.ai/code/session_016rWouaGy14w1zC4DETweoN

---

Generated by Claude Code

[giodefelice-agents]

USER feedback from an interactive session:

1. Don't show the dual rail encoding function into path, only show a Z spider with DualRail boxes.
2. For the last part, start with a universal photonic setup defined as a class with parameters for domain, codomain, classical and quantum memory types, the classically controlled unitary (defined via Kraus), an arbitrary state (input at every time step), an initial state (input at the first time step in the memory, default vacuum), a classical feedforward function. Then give the example you have by calling the class, showing it converges to a fixed point as before.

done in f0b0a66 — GHZ is now Z(0, 3) >> DualRail(1) ** 3 (no to_dual_rail), and UniversalSetup(dom, cod, quantum_memory, classical_memory, controlled, state, feedforward, initial=None) with the controlled-BS built from control.BitControlledBox's Kraus map and the loss as its environment; the example call converges to the same fixed point (0.5448 / 0.4552, at_time = eigen_fix = fix).

---

Generated by Claude Code