# Writing guide on quantum computing
**Writing guide on quantum computing** (this article) covers conventions specific to quantum computing articles in this wiki. Read [[general-writing-guide]] first for structure, paragraph, and code block conventions that apply across all articles.

The audience reminder from the general guide is especially relevant here: quantum computing draws on linear algebra, complex analysis, and abstract algebra that a typical computer engineering student has not yet seen. 

When a derivation uses a property that is not self-evident from the notation — that the Hamiltonian is Hermitian ($H^\dagger = H$), that the dagger of a product reverses order ($(AB)^\dagger = B^\dagger A^\dagger$), that trace is cyclic ($\mathrm{tr}(ABC) = \mathrm{tr}(CAB)$) — it is often worth adding a brief parenthetical at the point of use.

## Dirac notation

All quantum states are written using Dirac (bra-ket) notation. In DokuWiki + KaTeX, always use `\lvert` and `\rvert` instead of bare `|` so that delimiters scale correctly:

 - Ket: `$\lvert\psi\rangle$` → $\lvert\psi\rangle$
 - Bra: `$\langle\psi\rvert$` → $\langle\psi\rvert$
 - Inner product: `$\langle\phi\lvert\psi\rangle$` → $\langle\phi\lvert\psi\rangle$
 - Outer product / density matrix: `$\lvert\psi\rangle\langle\psi\rvert$` → $\lvert\psi\rangle\langle\psi\rvert$

Operators ($H$, $X$, $Y$, $Z$, $\rho$) are plain italic. Use the commutator $[A, B] = AB - BA$ and anticommutator $\{A, B\} = AB + BA$ inline without a display equation when they are definitional asides. Always carry $\hbar$ in equations — do not silently set $\hbar = 1$.

## Bloch sphere conventions

The Bloch sphere maps every single-qubit pure state to a point on the unit sphere. The axis conventions used throughout this wiki are:

 - North pole ($+z$): $\lvert 0\rangle$ — also written $\lvert\uparrow\rangle$ or the ground state
 - South pole ($-z$): $\lvert 1\rangle$
 - $+x$ pole: $\lvert +\rangle = (\lvert 0\rangle + \lvert 1\rangle)/\sqrt{2}$
 - $-x$ pole: $\lvert -\rangle = (\lvert 0\rangle - \lvert 1\rangle)/\sqrt{2}$
 - $+y$ pole: $\lvert +i\rangle = (\lvert 0\rangle + i\lvert 1\rangle)/\sqrt{2}$
 - $-y$ pole: $\lvert -i\rangle = (\lvert 0\rangle - i\lvert 1\rangle)/\sqrt{2}$

Mention the Bloch sphere position when describing any single-qubit state or gate. For gates, describe the axis and angle of rotation (e.g. "$X$ is a $\pi$ rotation about the $x$-axis").

## Article types

### Equation articles

Articles about equations (Schrödinger, von Neumann, Lindblad) follow this structure:

1. Bold the article name, give the physical context in 2–3 sentences.
2. Display the equation in a `$$...$$` block immediately after the intro paragraph — before any sections.
3. Dedicate one section per major term or concept in the equation. Don't mix several terms into one section.
4. Include a `## List of code implementations` section at the bottom.

**Correctness pitfalls for equations:**
 - Born rule: measurement probability **equals** the modulus squared — never "proportional to".
 - Dissipator in the Lindblad equation: the jump term is $L_k\rho L_k^\dagger$, not $L_k^\dagger\rho L_k$.
 - von Neumann equation uses the commutator $[H,\rho] = H\rho - \rho H$, which is not zero because matrix multiplication is non-commutative.

### Gate articles

Gate articles follow this structure:

1. Bold the gate name, 2–3 sentences: what it does in words, what family it belongs to.
2. Display the matrix in a `$$...$$` block.
3. Show the action on basis states as inline equations or a short display block.
4. Describe the Bloch sphere interpretation.
5. Include a `## List of code implementations` section at the bottom.

Gate matrices are written in standard computational basis order: rows and columns indexed $\lvert 0\rangle, \lvert 1\rangle$ (single-qubit) or $\lvert 00\rangle, \lvert 01\rangle, \lvert 10\rangle, \lvert 11\rangle$ (two-qubit).

### State articles

State articles follow this structure:

1. Bold the state name, 2–3 sentences: ket form, when it arises.
2. Display the ket as a `$$...$$` block.
3. Describe the Bloch sphere position (single-qubit) or entanglement structure (multi-qubit).
4. Include a `## List of code implementations` section.

Describe multi-qubit entangled states (Bell, GHZ, W) in terms of what happens to one qubit when another is measured — this is more informative than restating the ket.

### Implementation articles

Implementation articles are short: they contain one intro line, an explanation of how the code maps to the parent equation or concept, and one self-contained code block. The intro line follows the pattern:

```
[[parent-page|Parent concept]] implementation using Framework.
```

Name the file `{concept}-{framework}.txt` (e.g. `x-gate-qiskit.txt`, `lindblad-equation-qutip.txt`). Frameworks in use: **Qiskit** (circuits, state vectors), **QuTiP** (open systems, time evolution), **cuStateVec** (GPU low-level C), **CUDA-Q** (GPU kernel C++).

Before the code block, explain which solver or function maps to which LaTeX equation — this is the most useful thing an implementation article can do. Example: "`mesolve(c_ops=[])` integrates $\dot\rho = -i[H,\rho]$; adding entries to `c_ops` adds the dissipator terms."

## DAG and linking conventions

The page graph is a DAG (directed acyclic graph). Category/overview pages ([[quantum-gate]], [[quantum-state]], [[quantum-circuit]], [[quantum-error-correction]]) appear in the top-level list at [[list-of-quantum-computing-concepts]]. Leaf articles (x-gate, plus-state, born-rule) do **not** appear in the top-level list — they are reachable via their parent category page.

When linking:
 - Link a concept on its **first mention** in the article body, not on every occurrence.
 - Never link the article's own title — a page does not link to itself.
 - Always link [[dirac-notation]], [[density-matrix]], [[bloch-sphere]], [[hamiltonian]], [[probability-amplitude]] on first use if they appear in an article that is not itself that page.
 - Implementation articles link back to their parent page in the first line; no other links are needed unless the code uses a concept worth explaining.

## Common mistakes to avoid

 - **"Proportional to the square"** — wrong for Born rule. The probability equals the modulus squared.
 - **"Re-entangle" after measurement** — wrong phrasing. A gate (e.g. Hadamard) puts a collapsed state back into superposition; entanglement is a multi-qubit property.
 - **Bare `|` for bras/kets** — use `\lvert`/`\rvert`; bare pipes render ambiguously next to text and break in some KaTeX contexts.
 - **Listing leaf articles in the top-level concept list** — violates the DAG. Add them to their parent category page instead.
 - **Mixing equation derivations with prose in one section** — give derivation steps their own display equations; don't embed them in paragraphs.