PySparQ Quick Start¶

This tutorial introduces the basic usage of PySparQ.

Installation¶

pip install pysparq

Basic Concepts¶

PySparQ is built on the Register Level Programming paradigm, operating directly on named registers instead of individual quantum gates.

[ ]:

import pysparq as ps

# Clear the static state (must be called for every new program!)
ps.System.clear()

# Create registers
ps.System.add_register("counter", ps.UnsignedInteger, 4)  # 4-bit unsigned integer
ps.System.add_register("flag", ps.Boolean, 1)             # single qubit

# Create a sparse state
state = ps.SparseState()
print(f"Initial number of basis states: {state.size()}")

Initializing Registers¶

[ ]:

# Initialize register values with Init_Unsafe
ps.Init_Unsafe("counter", 5)(state)
ps.Init_Unsafe("flag", 0)(state)

# Print the state
ps.pprint(state)

Creating a Superposition¶

[ ]:

# Hadamard creates a uniform superposition
ps.Hadamard_Bool("flag")(state)

print("After Hadamard:")
ps.pprint(state)

Arithmetic Operations¶

[ ]:

# Create the result register
ps.System.add_register_synchronous("result", ps.UnsignedInteger, 4, state)

# Addition: result ^= counter + 3
ps.Add_UInt_ConstUInt("counter", 3, "result")(state)

print("After addition:")
ps.pprint(state)

Querying Register Information¶

[ ]:

# Get register metadata
print(f"counter size: {ps.System.size_of('counter')} bits")
print(f"counter type: {ps.System.type_of('counter')}")
print(f"counter ID: {ps.System.get_id('counter')}")
print(f"Total number of qubits: {ps.System.get_qubit_count()}")

Conditional Operations¶

[ ]:

# Create a conditional addition (executed when flag is non-zero)
ps.System.clear()
ps.System.add_register("a", ps.UnsignedInteger, 4)
ps.System.add_register("b", ps.UnsignedInteger, 4)
ps.System.add_register("result", ps.UnsignedInteger, 4)
ps.System.add_register("ctrl", ps.Boolean, 1)

state = ps.SparseState()
ps.Init_Unsafe("a", 3)(state)
ps.Init_Unsafe("b", 5)(state)
ps.Init_Unsafe("ctrl", 1)(state)  # ctrl = 1, condition is active

# Conditional addition
ps.Add_UInt_UInt("a", "b", "result").conditioned_by_nonzeros("ctrl")(state)

print("Conditional addition result:")
ps.pprint(state)

Summary¶

Core concepts of PySparQ:

System.clear() - call it at the start of every new program
add_register - create named registers
SparseState - sparse quantum state
Operators - operators transform the state
StatePrint - print the state to inspect results