builder

package
v1.2.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 19, 2026 License: MIT Imports: 5 Imported by: 0

Documentation

Overview

Package builder provides a fluent API for constructing quantum circuits.

Package builder provides a fluent API for constructing quantum circuits.

A Builder accumulates gate operations and measurements, then produces an immutable ir.Circuit via Builder.Build. Qubit indices are validated eagerly; the first error short-circuits all subsequent calls and is returned by Build. 

c, err := builder.New("bell", 2).
    H(0).
    CNOT(0, 1).
    MeasureAll().
    Build()

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Builder 

type Builder struct {
	// contains filtered or unexported fields
}

Builder accumulates operations and produces an immutable Circuit.

Example (Bell) 
package main

import (
	"fmt"

	"github.com/splch/goqu/circuit/builder"
)

func main() {
	c, err := builder.New("bell", 2).
		H(0).
		CNOT(0, 1).
		Build()
	if err != nil {
		panic(err)
	}
	stats := c.Stats()
	fmt.Printf("name=%s qubits=%d depth=%d gates=%d two_qubit=%d\n",
		c.Name(), c.NumQubits(), stats.Depth, stats.GateCount, stats.TwoQubitGates)
}

Output:

name=bell qubits=2 depth=2 gates=2 two_qubit=1
Example (Ghz) 
package main

import (
	"fmt"

	"github.com/splch/goqu/circuit/builder"
)

func main() {
	b := builder.New("ghz-4", 4).H(0)
	for i := 0; i < 3; i++ {
		b.CNOT(i, i+1)
	}
	c, err := b.Build()
	if err != nil {
		panic(err)
	}
	stats := c.Stats()
	fmt.Printf("qubits=%d depth=%d two_qubit=%d\n",
		c.NumQubits(), stats.Depth, stats.TwoQubitGates)
}

Output:

qubits=4 depth=4 two_qubit=3

func New 

func New(name string, nQubits int) *Builder

New creates a circuit builder for n qubits.

func (*Builder) Apply 

func (b *Builder) Apply(g gate.Gate, qubits ...int) *Builder

Apply adds an arbitrary gate on the specified qubits.

func (*Builder) Barrier 

func (b *Builder) Barrier(qubits ...int) *Builder

Barrier adds a barrier instruction (no-op marker for transpilation).

func (*Builder) Build 

func (b *Builder) Build() (*ir.Circuit, error)

Build finalizes and returns an immutable Circuit.

func (*Builder) CCX 

func (b *Builder) CCX(c0, c1, target int) *Builder

CCX applies a Toffoli (CCX) gate.

func (*Builder) CCZ added in v1.2.0 

func (b *Builder) CCZ(c0, c1, target int) *Builder

CCZ applies a doubly-controlled Z gate.

func (*Builder) CH added in v1.2.0 

func (b *Builder) CH(control, target int) *Builder

CH applies a controlled-Hadamard gate.

func (*Builder) CNOT 

func (b *Builder) CNOT(control, target int) *Builder

CNOT applies a CNOT (controlled-X) gate.

func (*Builder) CSX added in v1.2.0 

func (b *Builder) CSX(control, target int) *Builder

CSX applies a controlled-√X gate.

func (*Builder) CZ 

func (b *Builder) CZ(control, target int) *Builder

CZ applies a CZ (controlled-Z) gate.

func (*Builder) Compose 

func (b *Builder) Compose(c *ir.Circuit, qubitMap map[int]int) *Builder

Compose appends all operations from c into the builder, remapping qubit indices. nil qubitMap uses identity mapping (c's qubit N → builder's qubit N). Classical bits use identity mapping (c's clbit N → builder's clbit N).

func (*Builder) ComposeInverse 

func (b *Builder) ComposeInverse(c *ir.Circuit, qubitMap map[int]int) *Builder

ComposeInverse appends the inverse of c's operations (reversed order, each gate adjointed). Measurements, resets, and barriers are skipped. nil qubitMap uses identity mapping.

func (*Builder) Ctrl 

func (b *Builder) Ctrl(g gate.Gate, controls []int, targets ...int) *Builder

Ctrl wraps any gate with additional control qubits.

func (*Builder) DCX added in v1.2.0 

func (b *Builder) DCX(q0, q1 int) *Builder

DCX applies a DCX (double CNOT) gate.

func (*Builder) Delay added in v1.2.0 

func (b *Builder) Delay(qubit int, duration float64, unit string) *Builder

Delay idles a qubit for the given duration. The unit should be one of the gate.Unit* constants (e.g., gate.UnitNs).

func (*Builder) ECR added in v1.2.0 

func (b *Builder) ECR(q0, q1 int) *Builder

ECR applies an ECR (echoed cross-resonance) gate.

func (*Builder) FSim added in v1.2.0 

func (b *Builder) FSim(theta, phi float64, q0, q1 int) *Builder

FSim applies a fermionic simulation gate.

func (*Builder) For added in v1.2.0 

func (b *Builder) For(clbit int, start, end, step int, body func(*Builder)) *Builder

For executes body for each iteration in [start, end) with the given step. The iteration count is stored in the specified clbit (least-significant bit).

func (*Builder) GlobalPhase added in v1.2.0 

func (b *Builder) GlobalPhase(phi float64, q int) *Builder

GlobalPhase applies a global phase gate.

func (*Builder) H 

func (b *Builder) H(q int) *Builder

H applies a Hadamard gate.

func (*Builder) ISWAP added in v1.2.0 

func (b *Builder) ISWAP(q0, q1 int) *Builder

ISWAP applies an iSWAP gate.

func (*Builder) If 

func (b *Builder) If(clbit, value int, g gate.Gate, qubits ...int) *Builder

If adds a classically-conditioned gate. The gate is applied only when clbit == value.

func (*Builder) IfBlock 

func (b *Builder) IfBlock(clbit, value int, fn func(*Builder)) *Builder

IfBlock conditions multiple operations on clbit == value. The function fn is called with a sub-builder; all ops added inside are conditioned.

func (*Builder) IfElseBlock added in v1.2.0 

func (b *Builder) IfElseBlock(clbit, value int, ifBody, elseBody func(*Builder)) *Builder

IfElseBlock conditions operations on clbit == value, with an else branch.

func (*Builder) MCP 

func (b *Builder) MCP(phi float64, controls []int, target int) *Builder

MCP applies a multi-controlled Phase gate.

func (*Builder) MCX 

func (b *Builder) MCX(controls []int, target int) *Builder

MCX applies a multi-controlled X gate.

func (*Builder) MCZ 

func (b *Builder) MCZ(controls []int, target int) *Builder

MCZ applies a multi-controlled Z gate.

func (*Builder) Measure 

func (b *Builder) Measure(qubit, clbit int) *Builder

Measure adds a measurement of qubit to classical bit.

func (*Builder) MeasureAll 

func (b *Builder) MeasureAll() *Builder

MeasureAll adds measurements for all qubits to corresponding classical bits. Automatically sets numClbits to numQubits if not already set.

func (*Builder) PSwap added in v1.2.0 

func (b *Builder) PSwap(phi float64, q0, q1 int) *Builder

PSwap applies a parameterized SWAP gate.

func (*Builder) Phase 

func (b *Builder) Phase(phi float64, q int) *Builder

Phase applies a phase gate.

func (*Builder) PhasedXZ added in v1.2.0 

func (b *Builder) PhasedXZ(x, z, a float64, q int) *Builder

PhasedXZ applies a Cirq-style PhasedXZ gate.

func (*Builder) RX 

func (b *Builder) RX(theta float64, q int) *Builder

RX applies an RX rotation gate.

func (*Builder) RXX 

func (b *Builder) RXX(theta float64, q0, q1 int) *Builder

RXX applies an Ising XX rotation gate.

func (*Builder) RY 

func (b *Builder) RY(theta float64, q int) *Builder

RY applies an RY rotation gate.

func (*Builder) RYY 

func (b *Builder) RYY(theta float64, q0, q1 int) *Builder

RYY applies an Ising YY rotation gate.

func (*Builder) RZ 

func (b *Builder) RZ(theta float64, q int) *Builder

RZ applies an RZ rotation gate.

func (*Builder) RZZ 

func (b *Builder) RZZ(theta float64, q0, q1 int) *Builder

RZZ applies an Ising ZZ rotation gate.

func (*Builder) Reset 

func (b *Builder) Reset(qubit int) *Builder

Reset resets a qubit to |0⟩.

func (*Builder) Rot added in v1.2.0 

func (b *Builder) Rot(phi, theta, omega float64, q int) *Builder

Rot applies a PennyLane-style Rot gate.

func (*Builder) S 

func (b *Builder) S(q int) *Builder

S applies an S gate.

func (*Builder) SWAP 

func (b *Builder) SWAP(q0, q1 int) *Builder

SWAP applies a SWAP gate.

func (*Builder) SetMetadata 

func (b *Builder) SetMetadata(key, value string) *Builder

SetMetadata sets a metadata key-value pair.

func (*Builder) StatePrep 

func (b *Builder) StatePrep(amplitudes []complex128, qubits ...int) *Builder

StatePrep adds a state preparation gate.

func (*Builder) Switch added in v1.2.0 

func (b *Builder) Switch(clbits []int, cases map[int]func(*Builder), defaultBody func(*Builder)) *Builder

Switch branches on the integer value of the given classical bits. cases maps integer values to body functions. defaultBody (may be nil) executes if no case matches.

func (*Builder) Sycamore added in v1.2.0 

func (b *Builder) Sycamore(q0, q1 int) *Builder

Sycamore applies Google's Sycamore gate.

func (*Builder) SymCP 

func (b *Builder) SymCP(phi param.Expr, q0, q1 int) *Builder

SymCP applies a symbolic controlled-phase gate.

func (*Builder) SymFSim added in v1.2.0 

func (b *Builder) SymFSim(theta, phi param.Expr, q0, q1 int) *Builder

SymFSim applies a symbolic FSim gate.

func (*Builder) SymGlobalPhase added in v1.2.0 

func (b *Builder) SymGlobalPhase(phi param.Expr, q int) *Builder

SymGlobalPhase applies a symbolic GlobalPhase gate.

func (*Builder) SymPSwap added in v1.2.0 

func (b *Builder) SymPSwap(phi param.Expr, q0, q1 int) *Builder

SymPSwap applies a symbolic PSwap gate.

func (*Builder) SymPhase 

func (b *Builder) SymPhase(phi param.Expr, q int) *Builder

SymPhase applies a symbolic Phase gate.

func (*Builder) SymRX 

func (b *Builder) SymRX(theta param.Expr, q int) *Builder

SymRX applies a symbolic RX gate.

func (*Builder) SymRXX 

func (b *Builder) SymRXX(theta param.Expr, q0, q1 int) *Builder

SymRXX applies a symbolic Ising XX gate.

func (*Builder) SymRY 

func (b *Builder) SymRY(theta param.Expr, q int) *Builder

SymRY applies a symbolic RY gate.

func (*Builder) SymRYY 

func (b *Builder) SymRYY(theta param.Expr, q0, q1 int) *Builder

SymRYY applies a symbolic Ising YY gate.

func (*Builder) SymRZ 

func (b *Builder) SymRZ(theta param.Expr, q int) *Builder

SymRZ applies a symbolic RZ gate.

func (*Builder) SymRZZ 

func (b *Builder) SymRZZ(theta param.Expr, q0, q1 int) *Builder

SymRZZ applies a symbolic Ising ZZ gate.

func (*Builder) SymRot added in v1.2.0 

func (b *Builder) SymRot(phi, theta, omega param.Expr, q int) *Builder

SymRot applies a symbolic Rot gate.

func (*Builder) SymU1 added in v1.2.0 

func (b *Builder) SymU1(lambda param.Expr, q int) *Builder

SymU1 applies a symbolic U1 gate.

func (*Builder) SymU2 added in v1.2.0 

func (b *Builder) SymU2(phi, lambda param.Expr, q int) *Builder

SymU2 applies a symbolic U2 gate.

func (*Builder) SymU3 

func (b *Builder) SymU3(theta, phi, lambda param.Expr, q int) *Builder

SymU3 applies a symbolic U3 gate.

func (*Builder) T 

func (b *Builder) T(q int) *Builder

T applies a T gate.

func (*Builder) U1 added in v1.2.0 

func (b *Builder) U1(lambda float64, q int) *Builder

U1 applies a U1 (phase) gate.

func (*Builder) U2 added in v1.2.0 

func (b *Builder) U2(phi, lambda float64, q int) *Builder

U2 applies a U2 gate.

func (*Builder) U3 

func (b *Builder) U3(theta, phi, lambda float64, q int) *Builder

U3 applies the universal single-qubit gate.

func (*Builder) Unitary 

func (b *Builder) Unitary(name string, matrix []complex128, qubits ...int) *Builder

Unitary applies a custom unitary gate created from the given matrix. The name is used for display; the matrix must be a valid unitary (2x2, 4x4, or 8x8).

func (*Builder) While added in v1.2.0 

func (b *Builder) While(clbit, value int, body func(*Builder)) *Builder

While executes body repeatedly while clbit == value. At simulation time, iterations are capped at ir.MaxControlFlowIterations.

func (*Builder) WithClbits 

func (b *Builder) WithClbits(n int) *Builder

WithClbits sets the number of classical bits.

func (*Builder) X 

func (b *Builder) X(q int) *Builder

X applies a Pauli-X gate.

func (*Builder) Y 

func (b *Builder) Y(q int) *Builder

Y applies a Pauli-Y gate.

func (*Builder) Z 

func (b *Builder) Z(q int) *Builder

Z applies a Pauli-Z gate.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.