textbook

Documentation

Overview

Package textbook implements textbook quantum algorithms: Bernstein-Vazirani, Deutsch-Jozsa, and Simon's algorithm.

Index

• type BVConfig
• type BVResult
  • func BernsteinVazirani(ctx context.Context, cfg BVConfig) (*BVResult, error)
• type DJConfig
• type DJOracle
  • func BalancedOracle(mask int) DJOracle
  • func ConstantOracle(value int) DJOracle
• type DJResult
  • func DeutschJozsa(ctx context.Context, cfg DJConfig) (*DJResult, error)
• type SimonConfig
• type SimonOracle
  • func TwoToOneOracle(secret, numQubits int) SimonOracle
• type SimonResult
  • func Simon(ctx context.Context, cfg SimonConfig) (*SimonResult, error)

Types

type BVConfig

type BVConfig struct {
	// Secret is the hidden bitstring s. The oracle computes f(x) = s·x mod 2.
	Secret int
	// NumQubits is the number of input qubits.
	NumQubits int
	// Shots is the number of measurement shots. Default: 1024.
	Shots int
}

BVConfig specifies the Bernstein-Vazirani problem.

type BVResult

type BVResult struct {
	Circuit *ir.Circuit
	Counts  map[string]int
	Secret  int
}

BVResult holds the Bernstein-Vazirani output.

func BernsteinVazirani

func BernsteinVazirani(ctx context.Context, cfg BVConfig) (*BVResult, error)

BernsteinVazirani runs the Bernstein-Vazirani algorithm to recover a secret string s from the oracle f(x) = s·x mod 2.

The algorithm uses n+1 qubits (n input + 1 ancilla) and determines the secret in a single query.

type DJConfig

type DJConfig struct {
	// NumQubits is the number of input qubits.
	NumQubits int
	// Oracle is the black-box function to test.
	Oracle DJOracle
	// Shots is the number of measurement shots. Default: 1024.
	Shots int
}

DJConfig specifies the Deutsch-Jozsa problem.

type DJOracle

type DJOracle func(b *builder.Builder, inputs []int, ancilla int)

DJOracle applies a Deutsch-Jozsa oracle to the circuit. It receives the builder, input qubit indices, and the ancilla qubit index.

func BalancedOracle

func BalancedOracle(mask int) DJOracle

BalancedOracle returns a Deutsch-Jozsa oracle for a balanced function. The function computes f(x) = popcount(x AND mask) mod 2. For each bit i set in mask, a CNOT(input[i], ancilla) is applied.

func ConstantOracle

func ConstantOracle(value int) DJOracle

ConstantOracle returns a Deutsch-Jozsa oracle for a constant function. value=0: f(x)=0 for all x (does nothing). value=1: f(x)=1 for all x (applies X to the ancilla).

type DJResult

type DJResult struct {
	Circuit    *ir.Circuit
	Counts     map[string]int
	IsConstant bool
}

DJResult holds the Deutsch-Jozsa output.

func DeutschJozsa

func DeutschJozsa(ctx context.Context, cfg DJConfig) (*DJResult, error)

DeutschJozsa runs the Deutsch-Jozsa algorithm to determine whether a boolean function is constant (same output for all inputs) or balanced (returns 0 for half and 1 for the other half).

The algorithm uses n+1 qubits (n input + 1 ancilla) and determines the answer in a single query.

type SimonConfig

type SimonConfig struct {
	// NumQubits is the number of bits in the domain (n).
	NumQubits int
	// Oracle implements f: {0,1}^n -> {0,1}^n with f(x) = f(x XOR s).
	Oracle SimonOracle
	// MaxRounds is the maximum number of sampling rounds. Default: 10*NumQubits.
	MaxRounds int
	// Shots is the number of measurement shots per round. Default: 1024.
	Shots int
}

SimonConfig specifies Simon's problem.

type SimonOracle

type SimonOracle func(b *builder.Builder, inputs, outputs []int)

SimonOracle applies Simon's oracle to the circuit. It receives the builder, input qubit indices [0..n-1], and output qubit indices [n..2n-1].

func TwoToOneOracle

func TwoToOneOracle(secret, numQubits int) SimonOracle

TwoToOneOracle creates a Simon oracle for the given secret period. It implements a 2-to-1 function f with f(x) = f(x XOR secret).

Construction:

1. Copy inputs to outputs via CNOT: output = x.
2. Let h be the highest set bit of secret.
3. For each bit j set in secret, apply CNOT(input[h], output[j]).

This gives f(x) = x when x_h = 0, and f(x) = x XOR secret when x_h = 1, ensuring f(x) = f(x XOR secret) for all x.

type SimonResult

type SimonResult struct {
	Circuit   *ir.Circuit // last round's circuit
	Period    int         // recovered period s
	Equations []int       // collected y values
}

SimonResult holds Simon's algorithm output.

func Simon

func Simon(ctx context.Context, cfg SimonConfig) (*SimonResult, error)

Simon runs Simon's algorithm to find the period s of a function f: {0,1}^n -> {0,1}^n satisfying f(x) = f(x XOR s).

The algorithm uses 2n qubits (n input + n output). Each round produces a value y such that y·s = 0 mod 2. After collecting n-1 linearly independent equations, the period is recovered by Gaussian elimination over GF(2).