---
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

| Gate | Class | Parameters | Description | |------|-------|------------|-------------| | Hadamard | H | target | Superposition | | Pauli-X | X | target | Bit flip (NOT) | | Pauli-Y | Y | target | Y rotation | | Pauli-Z | Z | target | Phase flip | | CNOT | CNOT | control, target | Controlled-NOT | | CZ | CZ | control, target | Controlled-Z | | T Gate | T | target | π/8 gate | | S Gate | S | target | Phase gate | | Rx | Rx | target, theta | X-axis rotation | | Ry | Ry | target, theta | Y-axis rotation | | Rz | Rz | target, theta | Z-axis rotation | | CPhase | CPhase | control, target, theta | Controlled phase | | SWAP | SWAP | qubit_a, qubit_b | Swap two qubits |

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

---
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

Adoption

aradotso/skills/xq-py-quantum-vm

$ install --global

Security Scan Results

SKILL.md

Core Concepts

Basic Usage

Initialize the VM and Create a Circuit

Apply Quantum Gates

Run the Circuit

Measure Qubits

Sample Multiple Shots

Common Quantum Patterns

Bell State (Maximum Entanglement)

GHZ State (3-Qubit Entanglement)

Quantum Teleportation Circuit

Quantum Fourier Transform (QFT)

Parameterized Gates

Inspecting State

Configuration

Environment Variables

Gate Reference

Troubleshooting

ImportError on gates module

Statevector norm not 1.0

Reproducible random measurements

Qubit index out of range

Development & Testing

Resources

Related Skills

aradotso/skills/compose-performance-skills

aradotso/baguette-ios-simulator

aradotso/skills/claude-code-game-studios

aradotso/whatcable-macos-usb-inspector

aradotso/skills/xq-py-quantum-vm

$ install --global

Security Scan Results

SKILL.md

Core Concepts

Basic Usage

Initialize the VM and Create a Circuit

Apply Quantum Gates

Run the Circuit

Measure Qubits

Sample Multiple Shots

Common Quantum Patterns

Bell State (Maximum Entanglement)

GHZ State (3-Qubit Entanglement)

Quantum Teleportation Circuit

Quantum Fourier Transform (QFT)

Parameterized Gates

Inspecting State

Configuration

Environment Variables

Gate Reference

Troubleshooting

ImportError on gates module

Statevector norm not 1.0

Reproducible random measurements

Qubit index out of range

Development & Testing

Resources

Related Skills

aradotso/skills/compose-performance-skills

aradotso/baguette-ios-simulator

aradotso/skills/claude-code-game-studios

aradotso/whatcable-macos-usb-inspector