Skip to content

Commit 7012ecb

Browse files
KrastanovKrastanov
committed
misc cleanup of CI and agents
1 parent 7af6dd1 commit 7012ecb

File tree

4 files changed

+150
-155
lines changed

4 files changed

+150
-155
lines changed

‎.github/workflows/benchmark.yml‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,7 @@
11
name: Benchmarks
22
on:
33
pull_request_target:
4-
branches:
5-
- master
4+
branches: [master, main]
65
permissions:
76
pull-requests: write
87

‎.github/workflows/ci.yml‎

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -27,19 +27,14 @@ jobs:
2727
os:
2828
- ubuntu-latest
2929
threads:
30-
- '1'
31-
- '5'
30+
- '2'
3231
arch:
3332
- x64
3433
include:
3534
- arch: aarch64
3635
os: macos-latest
3736
version: '1'
3837
threads: '1'
39-
- arch: x64
40-
os: macos-latest
41-
version: '1'
42-
threads: '1'
4338
- arch: x64
4439
os: windows-latest
4540
version: '1'

‎AGENTS.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# PBCCompiler.jl
2+
3+
Tools for Pauli Based Computation (PBC), a modality of quantum computation.
4+
5+
## Project Structure
6+
7+
- `src/PBCCompiler.jl` - Main module with circuit operations and compiler infrastructure
8+
- `src/traversal.jl` - Circuit traversal utilities for gate simplifications
9+
- `src/affectedqubits.jl` - Query functions for qubit indices affected by operations
10+
- `src/plotting.jl` - Plotting function stubs (scaffolding for extensions)
11+
- `ext/PBCCompilerMakieExt/` - Makie extension for circuit visualization
12+
- `test/` - Test suite using TestItemRunner.jl
13+
- `benchmark/` - Performance benchmarks using BenchmarkTools.jl
14+
15+
## Dependencies
16+
17+
- **Moshi.jl** - Algebraic data types via `@data` macro
18+
- **QuantumClifford.jl** - Pauli operators and stabilizer formalism
19+
20+
## Key Concepts
21+
22+
### Circuit Operations (`CircuitOp`)
23+
Algebraic data type representing quantum circuit operations:
24+
- `Measurement` - Pauli measurement with classical bit output
25+
- `Pauli` - Pauli gate application
26+
- `ExpHalfPiPauli`, `ExpQuatPiPauli`, `ExpEighPiPauli` - Rotation gates (pi/2, pi/4, pi/8)
27+
- `PrepMagic` - Magic state preparation
28+
- `PauliConditional` - Pauli gate conditioned on another Pauli
29+
- `BitConditional` - Operation conditioned on classical bit
30+
31+
### Compilation Pipeline
32+
The `preprocess_circuit` function transforms circuits through stages:
33+
1. Remove Pauli conditionals
34+
2. Commute non-Clifford gates to front
35+
3. Group non-Clifford operations
36+
4. Commute measurements to end
37+
5. Remove non-Clifford gates (introduce magic states)
38+
6. Remove post-measurement operations
39+
40+
### Runtime
41+
- `QuantumRuntime` - Abstract type for quantum execution backends
42+
- `MockRuntime` - Testing runtime where measurements return deterministic results
43+
- `ComputerState` - Tracks circuit, instruction pointer, and memory state
44+
45+
### Circuit Traversal
46+
The `traversal` function (`src/traversal.jl`) applies transformations to adjacent pairs of circuit operations:
47+
```julia
48+
traversal(circuit, pair_transformation, direction=:right, starting_index=1, end_index=:end)
49+
```
50+
- `pair_transformation(op1, op2)` returns:
51+
- `(new_op1, new_op2)` tuple to replace the pair
52+
- Single operation to combine the pair into one
53+
- `nothing` to keep unchanged
54+
- Supports left-to-right (`:right`) or right-to-left (`:left`) traversal
55+
- Used for gate commutation, simplification, and compilation passes
56+
57+
**Note on Moshi types**: Use `Moshi.Data.isa_variant(op, CircuitOp.Pauli)` instead of `op isa CircuitOp.Pauli` to check variant types.
58+
59+
### Affected Qubits
60+
The `affectedqubits` function (`src/affectedqubits.jl`) returns the sorted list of qubit indices affected by an operation or circuit:
61+
```julia
62+
affectedqubits(op::CircuitOp.Type) -> Vector{Int}
63+
affectedqubits(circuit::Circuit) -> Vector{Int}
64+
```
65+
66+
### Circuit Visualization (Makie Extension)
67+
When Makie is loaded, the `PBCCompilerMakieExt` extension provides circuit plotting:
68+
```julia
69+
using CairoMakie # or GLMakie
70+
using PBCCompiler
71+
72+
circuit = Circuit([...])
73+
circuitplot(circuit) # Create a plot
74+
circuitplot!(ax, circuit) # Add to existing axis
75+
circuitplot_axis(fig[1,1], circuit) # Create complete figure panel
76+
```
77+
78+
**Plot features:**
79+
- Gates shown as colored rectangles spanning affected qubits
80+
- Horizontal qubit wire lines
81+
- Measurement results marked with classical bit index (e.g., "c0")
82+
- Conditional operations marked with dependency index (e.g., "?c0")
83+
- PrepMagic gates not visualized (placeholder for future)
84+
85+
**Configurable attributes:**
86+
- `gatewidth`, `qubitspacing` - Gate dimensions
87+
- `wirecolor`, `wirelinewidth` - Wire appearance
88+
- `paulicolor`, `measurementcolor`, etc. - Gate colors by variant
89+
90+
## Development
91+
92+
### Workflow
93+
1. Always pull latest master: `git pull`
94+
2. Create feature branches for new work
95+
3. Commit often at each change
96+
4. Update CLAUDE.md with new functionality
97+
5. Run tests before creating PRs
98+
6. Add benchmarks for new performance-critical functionality
99+
100+
### Docstring Guidelines
101+
- Docstrings are for **users**, not developers
102+
- Do not include implementation details (e.g., "uses pattern matching", "implemented via recursion")
103+
- Focus on: what the function does, its arguments, return values, and usage examples
104+
- Implementation notes belong in code comments, not docstrings
105+
106+
### Run tests
107+
```bash
108+
julia -tauto --project -e 'using Pkg; Pkg.test("PBCCompiler")'
109+
```
110+
111+
### Benchmarks
112+
Benchmarks are managed with BenchmarkTools.jl and run in CI via AirspeedVelocity.jl.
113+
114+
Run benchmarks locally:
115+
```bash
116+
julia -tauto --project=benchmark -e 'include("benchmark/benchmarks.jl"); run(SUITE)'
117+
```
118+
119+
**When to add benchmarks:**
120+
- New compilation passes or transformations
121+
- New traversal operations
122+
- Any function that processes circuits at scale
123+
- Performance-critical code paths
124+
125+
**Benchmark file structure:**
126+
- Add new benchmarks to `benchmark/benchmarks.jl`
127+
- Use `evals=1` for functions that modify state in-place
128+
- Use `setup=` to create fresh data for each evaluation
129+
- Group related benchmarks using `BenchmarkGroup`
130+
131+
### Julia invocation
132+
Always use the `-tauto` flag when launching Julia to utilize all available threads, which drastically speeds up compilation times:
133+
```bash
134+
julia -tauto --project
135+
```
136+
137+
### Related source code
138+
- QuantumClifford.jl source: `../QuantumClifford.jl`
139+
- QuantumInterface.jl source: `../QuantumInterface.jl`
140+
141+
### Reference paper
142+
- "Game of Surface Codes" - https://quantum-journal.org/papers/q-2019-03-05-128/pdf/
143+
144+
## Related Packages
145+
146+
- [QuantumClifford.jl](https://github.com/QuantumSavory/QuantumClifford.jl) - Stabilizer formalism
147+
- [BPGates.jl](https://github.com/QuantumSavory/BPGates.jl) - Bell-preserving gates

‎CLAUDE.md‎

Lines changed: 1 addition & 147 deletions
Original file line numberDiff line numberDiff line change
@@ -1,147 +1 @@
1-
# PBCCompiler.jl
2-
3-
Tools for Pauli Based Computation (PBC), a modality of quantum computation.
4-
5-
## Project Structure
6-
7-
- `src/PBCCompiler.jl` - Main module with circuit operations and compiler infrastructure
8-
- `src/traversal.jl` - Circuit traversal utilities for gate simplifications
9-
- `src/affectedqubits.jl` - Query functions for qubit indices affected by operations
10-
- `src/plotting.jl` - Plotting function stubs (scaffolding for extensions)
11-
- `ext/PBCCompilerMakieExt/` - Makie extension for circuit visualization
12-
- `test/` - Test suite using TestItemRunner.jl
13-
- `benchmark/` - Performance benchmarks using BenchmarkTools.jl
14-
15-
## Dependencies
16-
17-
- **Moshi.jl** - Algebraic data types via `@data` macro
18-
- **QuantumClifford.jl** - Pauli operators and stabilizer formalism
19-
20-
## Key Concepts
21-
22-
### Circuit Operations (`CircuitOp`)
23-
Algebraic data type representing quantum circuit operations:
24-
- `Measurement` - Pauli measurement with classical bit output
25-
- `Pauli` - Pauli gate application
26-
- `ExpHalfPiPauli`, `ExpQuatPiPauli`, `ExpEighPiPauli` - Rotation gates (pi/2, pi/4, pi/8)
27-
- `PrepMagic` - Magic state preparation
28-
- `PauliConditional` - Pauli gate conditioned on another Pauli
29-
- `BitConditional` - Operation conditioned on classical bit
30-
31-
### Compilation Pipeline
32-
The `preprocess_circuit` function transforms circuits through stages:
33-
1. Remove Pauli conditionals
34-
2. Commute non-Clifford gates to front
35-
3. Group non-Clifford operations
36-
4. Commute measurements to end
37-
5. Remove non-Clifford gates (introduce magic states)
38-
6. Remove post-measurement operations
39-
40-
### Runtime
41-
- `QuantumRuntime` - Abstract type for quantum execution backends
42-
- `MockRuntime` - Testing runtime where measurements return deterministic results
43-
- `ComputerState` - Tracks circuit, instruction pointer, and memory state
44-
45-
### Circuit Traversal
46-
The `traversal` function (`src/traversal.jl`) applies transformations to adjacent pairs of circuit operations:
47-
```julia
48-
traversal(circuit, pair_transformation, direction=:right, starting_index=1, end_index=:end)
49-
```
50-
- `pair_transformation(op1, op2)` returns:
51-
- `(new_op1, new_op2)` tuple to replace the pair
52-
- Single operation to combine the pair into one
53-
- `nothing` to keep unchanged
54-
- Supports left-to-right (`:right`) or right-to-left (`:left`) traversal
55-
- Used for gate commutation, simplification, and compilation passes
56-
57-
**Note on Moshi types**: Use `Moshi.Data.isa_variant(op, CircuitOp.Pauli)` instead of `op isa CircuitOp.Pauli` to check variant types.
58-
59-
### Affected Qubits
60-
The `affectedqubits` function (`src/affectedqubits.jl`) returns the sorted list of qubit indices affected by an operation or circuit:
61-
```julia
62-
affectedqubits(op::CircuitOp.Type) -> Vector{Int}
63-
affectedqubits(circuit::Circuit) -> Vector{Int}
64-
```
65-
66-
### Circuit Visualization (Makie Extension)
67-
When Makie is loaded, the `PBCCompilerMakieExt` extension provides circuit plotting:
68-
```julia
69-
using CairoMakie # or GLMakie
70-
using PBCCompiler
71-
72-
circuit = Circuit([...])
73-
circuitplot(circuit) # Create a plot
74-
circuitplot!(ax, circuit) # Add to existing axis
75-
circuitplot_axis(fig[1,1], circuit) # Create complete figure panel
76-
```
77-
78-
**Plot features:**
79-
- Gates shown as colored rectangles spanning affected qubits
80-
- Horizontal qubit wire lines
81-
- Measurement results marked with classical bit index (e.g., "c0")
82-
- Conditional operations marked with dependency index (e.g., "?c0")
83-
- PrepMagic gates not visualized (placeholder for future)
84-
85-
**Configurable attributes:**
86-
- `gatewidth`, `qubitspacing` - Gate dimensions
87-
- `wirecolor`, `wirelinewidth` - Wire appearance
88-
- `paulicolor`, `measurementcolor`, etc. - Gate colors by variant
89-
90-
## Development
91-
92-
### Workflow
93-
1. Always pull latest master: `git pull`
94-
2. Create feature branches for new work
95-
3. Commit often at each change
96-
4. Update CLAUDE.md with new functionality
97-
5. Run tests before creating PRs
98-
6. Add benchmarks for new performance-critical functionality
99-
100-
### Docstring Guidelines
101-
- Docstrings are for **users**, not developers
102-
- Do not include implementation details (e.g., "uses pattern matching", "implemented via recursion")
103-
- Focus on: what the function does, its arguments, return values, and usage examples
104-
- Implementation notes belong in code comments, not docstrings
105-
106-
### Run tests
107-
```bash
108-
julia -tauto --project -e 'using Pkg; Pkg.test("PBCCompiler")'
109-
```
110-
111-
### Benchmarks
112-
Benchmarks are managed with BenchmarkTools.jl and run in CI via AirspeedVelocity.jl.
113-
114-
Run benchmarks locally:
115-
```bash
116-
julia -tauto --project=benchmark -e 'include("benchmark/benchmarks.jl"); run(SUITE)'
117-
```
118-
119-
**When to add benchmarks:**
120-
- New compilation passes or transformations
121-
- New traversal operations
122-
- Any function that processes circuits at scale
123-
- Performance-critical code paths
124-
125-
**Benchmark file structure:**
126-
- Add new benchmarks to `benchmark/benchmarks.jl`
127-
- Use `evals=1` for functions that modify state in-place
128-
- Use `setup=` to create fresh data for each evaluation
129-
- Group related benchmarks using `BenchmarkGroup`
130-
131-
### Julia invocation
132-
Always use the `-tauto` flag when launching Julia to utilize all available threads, which drastically speeds up compilation times:
133-
```bash
134-
julia -tauto --project
135-
```
136-
137-
### Related source code
138-
- QuantumClifford.jl source: `../QuantumClifford.jl`
139-
- QuantumInterface.jl source: `../QuantumInterface.jl`
140-
141-
### Reference paper
142-
- "Game of Surface Codes" - https://quantum-journal.org/papers/q-2019-03-05-128/pdf/
143-
144-
## Related Packages
145-
146-
- [QuantumClifford.jl](https://github.com/QuantumSavory/QuantumClifford.jl) - Stabilizer formalism
147-
- [BPGates.jl](https://github.com/QuantumSavory/BPGates.jl) - Bell-preserving gates
1+
@AGENTS.md

0 commit comments

Comments
 (0)