Quick Start

Standalone simulator workbench

pysparq info
pysparq run --case ghz --qubits 32 --out results/ghz.json
pysparq run --case qft --qubits 6 --basis 3
pysparq run --case stateprep --qubits 8 --seed 20261109
pysparq gui

The installed package has its own local GUI with no external web assets. The bounded experiments use the actual CPU native simulator, expose complex amplitudes, and check independent references and inverse operations. Reports include logical qubits, sparse support, normalization, phase-sensitive error, native binary hash and separate construction/execution times. GHZ supports up to 32 qubits; Fourier and dense unitary state preparation support 2..10. These timings describe classical simulation, not quantum runtime or an application speedup certificate. The GUI runs each experiment in a separate subprocess with a 60-second deadline; it submits no hardware jobs.

Register-Level Programming

PySparQ adopts the “register-level programming” paradigm. Instead of composing circuits from individual gates, you operate directly on named quantum registers. The level of abstraction rises from qubits to quantum registers, and almost all operations take registers as their unit.

Basic Workflow

  1. Call System.clear() to clean up static state

  2. Declare registers (name, type, number of bits)

  3. Create SparseState() — the default constructor automatically creates the |0...0⟩ initial state

  4. Apply quantum operations (see the operator reference)

  5. Read out the measurement results with partial trace operators

Example: Quantum Addition

import pysparq as ps

# Step 1: clean up static state
ps.System.clear()

# Step 2: declare registers
ps.System.add_register("a", ps.UnsignedInteger, 4)
ps.System.add_register("b", ps.UnsignedInteger, 4)
ps.System.add_register("result", ps.UnsignedInteger, 4)

# Step 3: create a sparse quantum state (automatically creates the |a=0, b=0⟩ initial state)
state = ps.SparseState()

# Step 4: put the registers into superposition
ps.Hadamard_Int("a", 4)(state)
ps.Hadamard_Int("b", 4)(state)

# Quantum addition: result = a + b
ps.Add_UInt_UInt("a", "b", "result")(state)

# The state now holds a superposition of all possible sums
ps.pprint(state)

The example uses Hadamard_Int to put both registers into superposition and Add_UInt_UInt to add them. See Hadamard operations, arithmetic operators, and the debugging tools (pprint) for details.

Conditional Operations

Operations can be conditioned on the values of other registers (see Conditional Operations for the full reference):

# Add a control register
ps.AddRegister("control", ps.Boolean, 1)(state)

# Apply the operation only when control is |1>
ps.Add_UInt_UInt("a", "b").conditioned_by_nonzeros("control")(state)

Control Types

Next Steps

Try the same workflow interactively in the PySparQ Quick Start notebook, then continue with Core Concepts and Examples.