Xq Py Quantum Vm

---
name: xq-py-quantum-vm
description: Python implementation of the Quip Network's quantum virtual machine (xqvm)
triggers:
  - quantum virtual machine python
  - xqvm quip network
  - quantum circuit simulation python
  - xq-py quantum vm
  - quip network quantum python
  - simulate quantum gates python
  - quantum vm xqvm
  - xqvm-py quantum circuit
---

# xq-py Quantum Virtual Machine

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

`xqvm-py` is a Python implementation of the Quip Network's quantum virtual machine (xqvm). It provides quantum circuit simulation, gate operations, and qubit state management for quantum computing workflows on classical hardware.

---

## Installation

```bash
# Clone from GitLab
git clone https://gitlab.com/piqued/xqvm-py.git
cd xqvm-py

# Install dependencies
pip install -r requirements.txt

# Install as a package (if setup.py/pyproject.toml present)
pip install -e .

Core Concepts

• Qubit: The fundamental unit of quantum information. xqvm-py models qubits as statevectors.
• Gate: Quantum operations applied to qubits (Hadamard, CNOT, Pauli-X/Y/Z, etc.).
• Circuit: An ordered sequence of gate operations applied to a register of qubits.
• Measurement: Collapse the quantum state into a classical bit outcome.

Basic Usage

Initialize the VM and Create a Circuit

from xqvm import QuantumVM, QuantumCircuit

# Create a quantum virtual machine
vm = QuantumVM()

# Create a 2-qubit circuit
circuit = QuantumCircuit(num_qubits=2)

Apply Quantum Gates

from xqvm import QuantumCircuit
from xqvm.gates import H, X, Y, Z, CNOT, CZ, T, S

circuit = QuantumCircuit(num_qubits=2)

# Apply Hadamard gate to qubit 0 (creates superposition)
circuit.apply(H, target=0)

# Apply Pauli-X (NOT) gate to qubit 1
circuit.apply(X, target=1)

# Apply CNOT (controlled-NOT): control=0, target=1
circuit.apply(CNOT, control=0, target=1)

Run the Circuit

from xqvm import QuantumVM, QuantumCircuit
from xqvm.gates import H, CNOT

# Build Bell state circuit
circuit = QuantumCircuit(num_qubits=2)
circuit.apply(H, target=0)
circuit.apply(CNOT, control=0, target=1)

# Execute on the VM
vm = QuantumVM()
result = vm.run(circuit)

print(result.statevector)   # Complex amplitude vector
print(result.probabilities)  # Measurement probabilities per basis state

Measure Qubits

from xqvm import QuantumVM, QuantumCircuit
from xqvm.gates import H

circuit = QuantumCircuit(num_qubits=3)
circuit.apply(H, target=0)
circuit.apply(H, target=1)
circuit.apply(H, target=2)

vm = QuantumVM()
result = vm.run(circuit)

# Measure all qubits (collapses state, returns classical bits)
bits = result.measure()
print(bits)  # e.g. [0, 1, 0]

# Measure a specific qubit
bit = result.measure_qubit(0)
print(bit)  # 0 or 1

Sample Multiple Shots

from xqvm import QuantumVM, QuantumCircuit
from xqvm.gates import H, CNOT

circuit = QuantumCircuit(num_qubits=2)
circuit.apply(H, target=0)
circuit.apply(CNOT, control=0, target=1)

vm = QuantumVM()

# Run 1024 shots and collect measurement histogram
counts = vm.sample(circuit, shots=1024)
print(counts)  # e.g. {'00': 512, '11': 512}

Common Quantum Patterns

Bell State (Maximum Entanglement)

from xqvm import QuantumVM, QuantumCircuit
from xqvm.gates import H, CNOT

def bell_state():
    circuit = QuantumCircuit(num_qubits=2)
    circuit.apply(H, target=0)
    circuit.apply(CNOT, control=0, target=1)
    return circuit

vm = QuantumVM()
result = vm.run(bell_state())
counts = vm.sample(bell_state(), shots=2048)
print(counts)  # Should be ~50% '00', ~50% '11'

GHZ State (3-Qubit Entanglement)

from xqvm import QuantumVM, QuantumCircuit
from xqvm.gates import H, CNOT

def ghz_state():
    circuit = QuantumCircuit(num_qubits=3)
    circuit.apply(H, target=0)
    circuit.apply(CNOT, control=0, target=1)
    circuit.apply(CNOT, control=0, target=2)
    return circuit

vm = QuantumVM()
counts = vm.sample(ghz_state(), shots=1024)
print(counts)  # ~50% '000', ~50% '111'

Quantum Teleportation Circuit

from xqvm import QuantumVM, QuantumCircuit
from xqvm.gates import H, X, Z, CNOT

def teleportation_circuit():
    # 3 qubits: [message, alice, bob]
    circuit = QuantumCircuit(num_qubits=3)

    # Prepare message qubit in |+> state
    circuit.apply(H, target=0)

    # Create Bell pair between Alice and Bob
    circuit.apply(H, target=1)
    circuit.apply(CNOT, control=1, target=2)

    # Alice's operations
    circuit.apply(CNOT, control=0, target=1)
    circuit.apply(H, target=0)

    # Classically conditioned corrections on Bob's qubit
    # (In full teleportation, measure qubits 0 and 1 first)
    circuit.apply(X, target=2)
    circuit.apply(Z, target=2)

    return circuit

vm = QuantumVM()
result = vm.run(teleportation_circuit())
print(result.statevector)

Quantum Fourier Transform (QFT)

from xqvm import QuantumVM, QuantumCircuit
from xqvm.gates import H, CPhase
import math

def qft(num_qubits: int) -> QuantumCircuit:
    circuit = QuantumCircuit(num_qubits=num_qubits)
    for i in range(num_qubits):
        circuit.apply(H, target=i)
        for j in range(i + 1, num_qubits):
            angle = math.pi / (2 ** (j - i))
            circuit.apply(CPhase, control=j, target=i, theta=angle)
    return circuit

vm = QuantumVM()
result = vm.run(qft(4))
print(result.probabilities)

Parameterized Gates

from xqvm import QuantumCircuit
from xqvm.gates import Rx, Ry, Rz
import math

circuit = QuantumCircuit(num_qubits=1)

# Rotation gates with angle parameter
circuit.apply(Rx, target=0, theta=math.pi / 2)
circuit.apply(Ry, target=0, theta=math.pi / 4)
circuit.apply(Rz, target=0, theta=math.pi)

Inspecting State

from xqvm import QuantumVM, QuantumCircuit
from xqvm.gates import H

circuit = QuantumCircuit(num_qubits=2)
circuit.apply(H, target=0)
circuit.apply(H, target=1)

vm = QuantumVM()
result = vm.run(circuit)

# Full statevector (complex numpy array)
sv = result.statevector
print("Statevector:", sv)

# Probability of each basis state
probs = result.probabilities
for state, prob in enumerate(probs):
    print(f"|{state:02b}>: {prob:.4f}")

# Density matrix
dm = result.density_matrix
print("Density matrix shape:", dm.shape)

Configuration

from xqvm import QuantumVM

# Configure VM options
vm = QuantumVM(
    backend="statevector",   # 'statevector' or 'density_matrix'
    precision="complex128",  # NumPy dtype for amplitudes
    seed=42,                 # RNG seed for reproducible measurements
)

Environment Variables

# Optional: override default backend
export XQVM_BACKEND=statevector

# Optional: set global random seed
export XQVM_SEED=42

# Optional: enable debug/verbose output
export XQVM_DEBUG=1

Gate Reference

Troubleshooting

ImportError on gates module

# Ensure you installed from the repo root
pip install -e .
# Or add to PYTHONPATH
export PYTHONPATH=$(pwd):$PYTHONPATH

Statevector norm not 1.0

import numpy as np
result = vm.run(circuit)
norm = np.linalg.norm(result.statevector)
assert abs(norm - 1.0) < 1e-9, f"Unnormalized state: norm={norm}"

Reproducible random measurements

vm = QuantumVM(seed=123)
counts1 = vm.sample(circuit, shots=100)
vm2 = QuantumVM(seed=123)
counts2 = vm2.sample(circuit, shots=100)
assert counts1 == counts2  # Deterministic with same seed

Qubit index out of range

circuit = QuantumCircuit(num_qubits=3)
# Valid targets: 0, 1, 2
# This will raise IndexError:
# circuit.apply(H, target=3)

Development & Testing

# Run tests
pytest tests/

# Run with verbose output
pytest tests/ -v

# Run a specific test file
pytest tests/test_gates.py

# Lint
flake8 xqvm/

Resources

• GitLab Repository: https://gitlab.com/piqued/xqvm-py
• Quip Network: https://quipnetwork.io (check for official docs)
• Open Issues: https://gitlab.com/piqued/xqvm-py/-/issues