Skip to content

Add CCZ and CCX gate support#150

Open
glasses666 wants to merge 2 commits into
QuEraComputing:mainfrom
glasses666:codex/bounty-113
Open

Add CCZ and CCX gate support#150
glasses666 wants to merge 2 commits into
QuEraComputing:mainfrom
glasses666:codex/bounty-113

Conversation

@glasses666

@glasses666 glasses666 commented Jun 3, 2026

Copy link
Copy Markdown

Closes #113.

Summary

  • Add CCZ and CCX/Toffoli support by expanding both program-text shorthand and Circuit.append() calls into the existing Clifford+T instruction set.
  • Use the 7-T CCZ decomposition discussed in the issue, with CCX derived by H-conjugating the target.
  • Add matrix truth-table coverage for CCZ and CCX, plus shorthand-vs-append coverage.
  • Update the README and docs quick-start supported-instruction lists.

Scope note

Visualization support is left out intentionally, matching the issue discussion that SVG visualization can be deferred.

Validation

  • PYTHONPATH=src uv run pytest -q -> 1087 passed in 46.24s
  • PYTHONPATH=src uv run pytest test/unit/test_circuit.py -q -> 192 passed in 1.22s
  • PYTHONPATH=src uv run pytest test/integration/test_gate_unitaries.py -q -> 117 passed in 2.27s
  • PYTHONPATH=src uv run ruff check src/tsim/utils/program_text.py src/tsim/circuit.py test/unit/test_circuit.py -> All checks passed!
  • PYTHONPATH=src uv run black --check src/tsim/utils/program_text.py src/tsim/circuit.py test/unit/test_circuit.py -> 3 files would be left unchanged
  • PYTHONPATH=src uv run pyright src/tsim/circuit.py src/tsim/utils/program_text.py test/unit/test_circuit.py -> 0 errors, 0 warnings, 0 informations

Note: in my local checkout, bare uv run pytest did not put src/ on sys.path, so I used PYTHONPATH=src for the validation commands above.

AI disclosure

AI-assisted with OpenAI Codex; the diff was reviewed and locally verified before submission.

Issue QuEraComputing#113 asks for native CCZ and CCX/Toffoli support without taking on visualization. The implementation keeps the simulator path simple by expanding both shorthand and append API usage into the existing Clifford+T instruction set, using the collaborator-approved 7-T CCZ decomposition and deriving CCX by H-conjugating the target.

Constraint: Stim does not parse CCZ or CCX instructions directly

Constraint: Visualization support is explicitly out of scope for the bounty issue

Rejected: Add direct Stim/GATE_TABLE native instructions | stim.Circuit would still reject source program text before tsim parsing

Confidence: high

Scope-risk: narrow

Directive: Keep CCZ and CCX behavior aligned across program text parsing and Circuit.append

Tested: PYTHONPATH=src uv run pytest -q (1087 passed)

Tested: PYTHONPATH=src uv run ruff check src/tsim/utils/program_text.py src/tsim/circuit.py test/unit/test_circuit.py

Tested: PYTHONPATH=src uv run black --check src/tsim/utils/program_text.py src/tsim/circuit.py test/unit/test_circuit.py

Tested: PYTHONPATH=src uv run pyright src/tsim/circuit.py src/tsim/utils/program_text.py test/unit/test_circuit.py

Not-tested: SVG/timeline visualization for CCZ/CCX, per issue scope
@rafaelha

rafaelha commented Jun 5, 2026

Copy link
Copy Markdown
Collaborator

Thanks for the contribution, this looks great! Could you also add support for tags?

Currently,

c = tsim.Circuit("""
X 0
CCX[tag] 0 1 2
M 2
""")

fails with

ValueError: Could not parse 'CCX' in program text.

The expected behavior is to expand the CCX with tags, i.e.

X 0
H[tag] 2
CX[tag] 1 2
T_DAG[tag] 2
CX[tag] 0 2
T[tag] 2
CX[tag] 1 2
T_DAG[tag] 2
CX[tag] 0 2
T[tag] 1 2
CX[tag] 0 1
T[tag] 0
T_DAG[tag] 1
CX[tag] 0 1
H[tag] 2
M 2

I think after that, this is good to be merged!

Maintainer review pointed out that tagged CCX/CCZ program-text instructions should expand into tagged primitive instructions. The fix carries the user tag through the decomposition while preserving the internal T-family marker used to model non-Clifford gates on top of Stim.

Constraint: Stim tags already encode tsim T-family gates, so user tags need a composed internal representation.

Confidence: high

Scope-risk: narrow

Tested: PYTHONPATH=src uv run pytest test/unit/utils/test_program_text.py test/unit/test_circuit.py test/unit/core/test_parse.py test/unit/external/test_vec_sampler.py test/unit/utils/test_diagram.py test/unit/utils/test_clifford.py -q

Tested: PYTHONPATH=src uv run pytest -q

Tested: PYTHONPATH=src uv run ruff check src test

Tested: PYTHONPATH=src uv run black --check src/tsim/core/tags.py src/tsim/utils/program_text.py src/tsim/circuit.py src/tsim/core/parse.py src/tsim/external/vec_sim/vec_sampler.py src/tsim/utils/clifford.py src/tsim/utils/diagram.py test/unit/utils/test_program_text.py test/unit/test_circuit.py

Tested: PYTHONPATH=src uv run pyright src/tsim/core/tags.py src/tsim/utils/program_text.py src/tsim/circuit.py src/tsim/core/parse.py src/tsim/external/vec_sim/vec_sampler.py src/tsim/utils/clifford.py src/tsim/utils/diagram.py
@glasses666

glasses666 commented Jun 5, 2026

Copy link
Copy Markdown
Author

Fixed in the latest push. CCX[tag] and CCZ[tag] now preserve the tag across the expanded gates, and the exact CCX[tag] example is covered by a unit test.

Local checks passed: pytest -q (1093 passed), ruff check src test, black --check, and targeted pyright.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Feature Request: Add Support for native CCZ Gate

2 participants