statevector

Documentation

Overview

Package statevector implements a full statevector quantum simulator supporting up to 28 qubits.

The simulator stores the state as a []complex128 slice and applies gates via stride-based index arithmetic. For 17 or more qubits, gate application is automatically parallelized across available cores.

Sim.Run evolves the state and samples measurement counts. Sim.Evolve applies gates without measuring, leaving the statevector accessible via Sim.StateVector for inspection or expectation values.

Package statevector implements a full statevector quantum simulator.

Index

• type Sim
  • func New(numQubits int) *Sim
  • func (s *Sim) Evolve(c *ir.Circuit) error
  • func (s *Sim) ExpectPauliString(ps pauli.PauliString) float64
  • func (s *Sim) ExpectPauliSum(ps pauli.PauliSum) float64
  • func (s *Sim) ExpectationValue(qubits []int) float64
  • func (s *Sim) Run(c *ir.Circuit, shots int) (map[string]int, error)
  • func (s *Sim) RunDynamic(c *ir.Circuit, shots int) (map[string]int, error)
  • func (s *Sim) StateVector() []complex128

Examples

• Sim.Evolve
• Sim.Run

Types

type Sim

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

Sim simulates a circuit via full statevector evolution.

func New

func New(numQubits int) *Sim

New creates a simulator initialized to |0...0>.

func (*Sim) Evolve

func (s *Sim) Evolve(c *ir.Circuit) error

Evolve applies all gate operations without measuring, leaving the statevector accessible.

Example

package main

import (
	"fmt"
	"math"

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

func main() {
	// Build a Bell circuit and inspect the statevector.
	c, err := builder.New("bell", 2).
		H(0).
		CNOT(0, 1).
		Build()
	if err != nil {
		panic(err)
	}

	sim := statevector.New(2)
	if err := sim.Evolve(c); err != nil {
		panic(err)
	}

	// The Bell state has non-zero amplitudes only for |00> and |11>.
	sv := sim.StateVector()
	for i, amp := range sv {
		p := real(amp)*real(amp) + imag(amp)*imag(amp)
		if p > 1e-10 {
			fmt.Printf("|%02b|^2 = %.1f\n", i, math.Round(p*10)/10)
		}
	}
}

Output:

|00|^2 = 0.5
|11|^2 = 0.5

func (*Sim) ExpectPauliString

func (s *Sim) ExpectPauliString(ps pauli.PauliString) float64

ExpectPauliString computes Re(⟨psi|P|psi⟩) for a Pauli string P. For Hermitian observables (real coefficients), the imaginary part is zero. For non-Hermitian observables, use pauli.Expect directly for complex128.

func (*Sim) ExpectPauliSum

func (s *Sim) ExpectPauliSum(ps pauli.PauliSum) float64

ExpectPauliSum computes Re(⟨psi|H|psi⟩) for a Hamiltonian H (sum of Pauli strings). For Hermitian observables (real coefficients), the imaginary part is zero. For non-Hermitian observables, use pauli.ExpectSum directly for complex128.

func (*Sim) ExpectationValue

func (s *Sim) ExpectationValue(qubits []int) float64

ExpectationValue computes <psi|O|psi> for a diagonal Pauli-Z observable specified as a list of qubit indices. For example, [0, 1] computes <Z0 Z1>. The result is rounded to 14 decimal places to clean up floating-point noise.

func (*Sim) Run

func (s *Sim) Run(c *ir.Circuit, shots int) (map[string]int, error)

Run executes the circuit and returns measurement counts. For dynamic circuits (mid-circuit measurement, feed-forward, reset), it automatically uses per-shot simulation with state collapse.

Example

package main

import (
	"fmt"

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

func main() {
	// Build a circuit that always produces |11>.
	c, err := builder.New("x2", 2).
		X(0).
		X(1).
		MeasureAll().
		Build()
	if err != nil {
		panic(err)
	}

	sim := statevector.New(2)
	counts, err := sim.Run(c, 100)
	if err != nil {
		panic(err)
	}
	fmt.Printf("11: %d shots\n", counts["11"])
}

Output:

11: 100 shots

func (*Sim) RunDynamic

func (s *Sim) RunDynamic(c *ir.Circuit, shots int) (map[string]int, error)

RunDynamic executes a dynamic circuit (mid-circuit measurement, feed-forward, reset) by simulating each shot independently with projective measurement and state collapse.

func (*Sim) StateVector

func (s *Sim) StateVector() []complex128

StateVector returns a copy of the current statevector.