# Multivariate Multicycle Codes Project Guidance

This project contains a draft paper and a Minneapolis reveal.js talk about
multivariate multicycle (MM) quantum error-correcting codes. The central idea is
that MM codes are CSS codes built from Koszul complexes over multivariate
quotient rings. The construction unifies familiar algebraic qLDPC families
while producing a length-5 chain complex in which X/Z parity checks and X/Z
metachecks are neighboring boundary maps.

## Entry Points

- `paper/main.tex` is the source of the manuscript.
- `paper/AGENTS.md` documents the manuscript structure, active figures, tables,
  and the core chain-complex message.
- `2026-Minneapolis/index.html` is the reveal.js draft for the Minneapolis
  presentation.
- `2026-Minneapolis/custom.css` is the local deck styling.

The paper subfolder is its own git repository. Treat `paper/.git` as local to
the paper and run git commands inside `paper/` when checking manuscript status.

## Paper Content

The paper introduces MM codes from quotient rings of the form

```tex
S = F_2[w,x,y,z] / <w^ell - 1, x^m - 1, y^p - 1, z^r - 1>
```

with chosen polynomials `F, G, H, I in S`. For the main `t=4` construction, the
Koszul complex is

```tex
0 <- K_0 <-partial_1- K_1 <-partial_2- K_2
  <-partial_3- K_3 <-partial_4- K_4 <- 0.
```

The semantic roles are:

- `K_4 ~= S`: Z metachecks.
- `K_3 ~= S^4`: Z parity checks.
- `K_2 ~= S^6`: physical qubits.
- `K_1 ~= S^4`: X parity checks.
- `K_0 ~= S`: X metachecks.

The key matrix identifications are:

```tex
P_Z = partial_3
P_X = partial_2^T
M_Z = partial_4
M_X = partial_1^T
```

The chain identities imply the code constraints:

```tex
partial_4 partial_3 = 0     <=>     M_Z P_Z = 0
partial_3 partial_2 = 0     <=>     P_Z P_X^T = 0
partial_2 partial_1 = 0     <=>     M_X P_X = 0
```

Keep this notation synchronized between the paper, `paper/AGENTS.md`, and any
talk slides.

## Minneapolis Deck

The Minneapolis deck is intentionally sparse. Slides are a visual backdrop for
spoken explanations, not a transcript. Prefer:

- one title plus one formula,
- one title plus one simple block diagram,
- one title plus one figure,
- fragment-based blocks for conceptual sequences.

Avoid paragraphs on slides. If explanatory detail is needed, place it in HTML
comments near the slide, not visible text. The current draft follows the user
requested structure:

- intro: Stefan, UMass group, open source, QNumerics;
- good classical codes;
- the quantum consistency problem `P_X P_Z^T = 0`;
- representation choices: expander graph codes versus chain complexes;
- homological algebra and the surface-code chain complex;
- single-shot decoding and metachecks;
- the MM/Koszul construction;
- code quality, confinement, and table placeholders;
- simulation plots;
- closing slides on QuantumClifford.jl, QNumerics, and hiring.

For slide inspection from the archive root, use:

```bash
tools/reveal_text.py 2026-Multivariate-Multicycle-Codes/2026-Minneapolis/index.html --max-chars 20000
tools/reveal_lint.py 2026-Multivariate-Multicycle-Codes/2026-Minneapolis/index.html
```

Opening `2026-Minneapolis/index.html` directly in a browser should work for a
quick pass. Use a local static server only if browser security or PDF/image
rendering gets in the way.

## Assets

Keep assets local to the folder that uses them. Do not centralize shared plots,
logos, CSS, or reveal.js vendor files unless explicitly asked.

The Minneapolis folder already has the reveal.js vendor tree and many reusable
group-overview assets copied from the meet-and-greet deck, including:

- `qnumerics.png` for the QNumerics Summer School slides;
- `MMvsother.png` for older single-shot-code overview material;
- `codetree.png`, `savorylogo.png`, `models.png`, and related open-source
  assets;
- `CQN_Horizontal_White.png` and `aspennet.webp` for community/networking
  context.

The current Minneapolis draft also uses paper plots copied into the talk folder:

- `tesseract_LER_vs_p.png`;
- `PhenomenologicalNoiseModelXBasis.png`;
- `PhenomenologicalNoiseModelZBasis.png`;
- `CircuitLevelNoiseX.png`;
- `CircuitLevelNoiseZ.png`;
- `plateau_xz_T15.png`;
- `circ_plateau_xz_T10.png`.

The deck contains explicit placeholders for figures that should be designed in
a later pass, especially the confinement-profile comparison and selected code
table. Do not replace those placeholders with dense screenshots unless asked;
the intended second pass is a distilled visual, not a full paper table.

## Editing Style

- Preserve the dark reveal.js theme and local `custom.css` idioms.
- Use the local `.blocks`, `.block`, `.chain`, `.placeholder`, `.plot`, and
  bibliography helpers for sparse diagrams.
- Inline styles are acceptable for one-off slide sizing, matching the archive's
  reveal.js style.
- Use KaTeX notation already present in the paper: `P_X`, `P_Z`, `M_X`,
  `M_Z`, `K_i`, `S`, `F`, `G`, `H`, `I`, and `\partial_i`.
- Keep the orientation of the `t=4` complex consistent with the paper:
  `K_2` is the physical-qubit space, `P_Z = partial_3`,
  `P_X = partial_2^T`, `M_Z = partial_4`, and `M_X = partial_1^T`.
- For image-heavy simulation slides, use a single plot or a two-panel pair.
  Avoid surrounding plots with explanatory prose.
- Put future asset instructions in HTML comments or visible placeholder boxes.

## Do Not Edit For Normal Content Work

- `2026-Minneapolis/dist/`
- `2026-Minneapolis/plugin/`
- `2026-Minneapolis/.vscode/`
- `paper/.git/`