UnitaryHack 2026 - issue #142

[Mostafa-Atallah2020]

Fixes #142

Adds the parametric Pauli-rotation gates R_XX, R_YY, R_ZZ, and the general R_PAULI, matching the clifft two-qubit Pauli rotations reference. R_PAULI(theta) P0*P1*... applies exp(-i * theta * pi/2 * P0 P1 ...) for an arbitrary Pauli product, and R_XX/R_YY/R_ZZ are surface shorthands for the two-qubit same-axis case.

Following the issue's suggested approach, the gates are encoded on top of stim's existing SPP/tag pipeline rather than as a new instruction kind. The angle is carried in the tag the same way R_X/R_Y/R_Z carry theta=...*pi via I[R_X(theta=...*pi)], and R_XX/R_YY/R_ZZ lower to SPP[R_PAULI(theta=α*pi)] P0*P1. The lowering lives in Circuit.append, the new simulation primitive core/instructions.r_pauli generalises SPP (θ=1/2) and TPP (θ=1/4) to arbitrary angles via the existing _pauli_product_phase mechanism, and core/parse.parse_stim_circuit dispatches tagged SPP/SPP_DAG instructions to it after a new validator rejects duplicate qubits within a single Pauli product and caps targets at 64 per instruction, both checked on the raw un-reduced target list.

Clifford-angle rotations stay first-class. is_half_pi_multiple now recognises SPP[R_PAULI(theta=k/2*pi)], and a new _expand_clifford_spp helper rewrites such instructions (including SPP_DAG) into the equivalent tag-free SPP / SPP+SPP / SPP_DAG sequence so simplification keeps producing pure-Clifford output. The shorthand layer is symmetric. shorthand_to_stim rewrites R_XX(α) 0 1, R_YY(α) 0 1, R_ZZ(α) 0 1, and R_PAULI(α) X0*Y1 into the tagged-SPP form, and stim_to_shorthand runs the inverse with the same-axis collapse applied before the general one in both directions so the R_XX/R_YY/R_ZZ surface form survives round-trips. Daggered forms work for free because the negated angle threads through r_pauli's existing dagger parameter.

Tests cover Stim-parity at Clifford angles, arbitrary-angle unitaries against the analytic cos(α π/2)·I − i sin(α π/2)·PP form (Kronecker-expanded for general R_PAULI), inverse round-trips via the existing inverse-of-inverse identity coverage, and the parser's duplicate-qubit and 64-qubit-cap validation paths. test/helpers/gate_matrices.py gains closed-form unitaries for the four new gates. The existing suite is untouched and uv run just coverage reports 95% on the committed tree (1e1b74f). Docs are updated in CHANGELOG.md (Unreleased entry) and in the Stim-API parity note in README.md / docs/index.md.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ba4b1fa393

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".