Skip to main content

​
Quick Start

This tutorial will guide you through running your first quantum simulations with QC. You’ll learn how to simulate quantum circuits and perform molecular ground state calculations.

​
Your First Quantum Circuit

Let’s start by running the quantum computer simulator with all three physics backends.

​
Running the Simulator

Execute the quantum computer with the following command: 
python3 quantum_computer.py \
  --hamiltonian-checkpoint hamiltonian.pth \
  --schrodinger-checkpoint checkpoint_phase3_training_epoch_18921_20260224_154739.pth \
  --dirac-checkpoint best_dirac.pth \
  --grid-size 16 \
  --hidden-dim 32 \
  --expansion-dim 64 \
  --device cpu
The simulator automatically loads all three backends and runs a comprehensive test suite including Bell states, GHZ states, Grover’s algorithm, and phase coherence tests.

​
Understanding the Output

The simulator runs three backends in parallel and produces identical results: 
--- Backend: HAMILTONIAN ---
[Bell State]  expected: P(|00>)=0.5, P(|11>)=0.5, entropy=1 bit
MeasurementResult (2 qubits)
  Most probable: |00>  P=0.5000
  Shannon entropy: 1.0000 bits
  Top states:
    |00>  P=0.5000
    |11>  P=0.5000

​
Test Results

The simulator validates 22 phase coherence tests: 
======================================================================
PHASE COHERENCE & UNITARITY TEST SUITE
======================================================================

--- Group 1: Single-qubit phase algebra ---
  [PASS] HZH = X  (|0>->|1>):  P(|1>)=1.0000
  [PASS] HXH = Z  (|0>->|0>):  P(|1>)=0.0000
  [PASS] XX = I   (|0>->|0>):  P(|1>)=0.0000

--- Group 2: Two-qubit phase-sensitive interference ---
  [PASS] H CNOT CNOT H = I  (P(|00>)=1.0000)
  [PASS] SWAP |01> = |10>   (P(|10>)=1.0000)

--- Group 3: Norm preservation (unitarity) ---
  [PASS] Norm preserved after H: sum(P)=1.00000000
  [PASS] Norm preserved after Bell: sum(P)=1.00000000

--- Group 4: Entanglement (Shannon entropy) ---
  [PASS] Bell state entropy = 1 bit  (got 1.0000)
  [PASS] GHZ-3 entropy = 1 bit  (got 1.0000)

======================================================================
ALL TESTS PASSED  (22/22)
======================================================================

​
Molecular Ground State Calculation

Now let’s calculate the ground state energy of molecular hydrogen (H₂) using Variational Quantum Eigensolver (VQE).

​
Run Molecular Simulation

python3 molecular_sim.py --molecule H2
  • --molecule: Molecule to simulate (currently supports: H2)
  • --max-iter: Maximum VQE iterations (default: 100)
  • --hamiltonian-checkpoint: Path to Hamiltonian weights
  • --schrodinger-checkpoint: Path to Schrödinger weights
  • --dirac-checkpoint: Path to Dirac weights
  • --grid-size: Spatial grid size (default: 16)
  • --hidden-dim: Neural network hidden dimension (default: 32)
  • --expansion-dim: Neural network expansion dimension (default: 64)
  • --seed: Random seed for reproducibility (default: 42)

​
Molecular Simulation Output

The VQE optimizer converges to the exact ground state:
1

Initialization

2026-03-01 22:51:27,739 | MolecularSimulator | INFO | Loaded H2 from PySCF: HF=-1.11699900, FCI=-1.13730604, E_nuc=0.719969
2026-03-01 22:51:27,805 | MolecularSimulator | INFO | Starting VQE for H2 (4 qubits)
2026-03-01 22:51:27,805 | MolecularSimulator | INFO | HF state: |1100> (2 e-, 4 qubits)
2

Hamiltonian Verification

2026-03-01 22:51:28,825 | MolecularSimulator | INFO | OpenFermion JW: 14 Pauli terms, E_nuc=-0.090579 Ha
2026-03-01 22:51:28,837 | MolecularSimulator | INFO | Verification: E_HF(calc)=-1.11699900 Ha, E_HF(target)=-1.11699900 Ha
3

UCCSD Ansatz

2026-03-01 22:51:28,858 | MolecularSimulator | INFO | UCCSD: 4 singles + 1 doubles = 5 parameters
2026-03-01 22:51:28,869 | MolecularSimulator | INFO | [check] theta=0: E=-1.11699900 Ha  ✓ identity
4

Parameter Optimization

Scanning double amplitude:
  theta_d=-0.10  E=-1.13707997 Ha ← best
  theta_d=+0.00  E=-1.11699900 Ha

iter   1: E=-1.13707997 Ha  Δ_FCI=2.26e-04
iter  20: E=-1.13730604 Ha  Δ_FCI=1.54e-10

Optimizer: CONVERGENCE: RELATIVE REDUCTION OF F <= FACTR*EPSMCH  (30 evals)
5

Final Results

Final: E_VQE=-1.13730604  E_FCI=-1.13730604  corr=100.0%

============================================================
  VQE Result: H2  [openfermion_jw]
============================================================
  Qubits: 4
  Parameters: 5
────────────────────────────────────────────────────────────
  HF energy  : -1.11699900 Ha
  VQE energy : -1.13730604 Ha
  FCI energy : -1.13730604 Ha
────────────────────────────────────────────────────────────
  |VQE-FCI|  : 1.31e-11 Ha
  Correlation: 100.0%
============================================================
The VQE calculation achieves 100% correlation energy capture with error |VQE-FCI| = 1.31×10⁻¹¹ Ha, which is at machine precision!

​
Building Custom Circuits

Here’s how to create and run custom quantum circuits programmatically:
quantum_circuit_example.py
from quantum_computer import QuantumComputer, QuantumCircuit, SimulatorConfig

# Configure simulator
config = SimulatorConfig(
    hamiltonian_checkpoint="hamiltonian.pth",
    schrodinger_checkpoint="checkpoint_phase3_training_epoch_18921_20260224_154739.pth",
    dirac_checkpoint="best_dirac.pth",
    grid_size=16,
    hidden_dim=32,
    expansion_dim=64,
    device="cpu"
)

# Initialize quantum computer
qc = QuantumComputer(config)

# Build a Bell state circuit
circuit = QuantumCircuit(2)
circuit.h(0)           # Hadamard on qubit 0
circuit.cnot(0, 1)     # CNOT with control=0, target=1

# Run circuit with Schrödinger backend
result = qc.run(circuit, backend="schrodinger")

# Display results
print(result)
print(f"\nEntropy: {result.entropy():.4f} bits")
print(f"Most probable: |{result.most_probable_bitstring()}>")
Output: 
MeasurementResult (2 qubits)
  Most probable: |00>  P=0.5000
  Shannon entropy: 1.0000 bits
  Top states:
    |00>  P=0.5000
    |11>  P=0.5000
  Per-qubit marginals:
    q0: P(|1>)=0.5000  <Z>=+0.0000  Bloch=(+0.000,-0.000,+0.000)
    q1: P(|1>)=0.5000  <Z>=+0.0000  Bloch=(+0.000,-0.000,+0.000)

Entropy: 1.0000 bits
Most probable: |00>

​
Available Quantum Gates

QC supports a comprehensive set of quantum gates: 
circuit.h(0)              # Hadamard
circuit.x(0)              # Pauli-X (NOT)
circuit.y(0)              # Pauli-Y
circuit.z(0)              # Pauli-Z
circuit.s(0)              # Phase gate (√Z)
circuit.t(0)              # T gate (√S)
circuit.rx(0, theta)      # Rotation around X-axis
circuit.ry(0, theta)      # Rotation around Y-axis
circuit.rz(0, theta)      # Rotation around Z-axis

circuit.cnot(0, 1)        # Controlled-NOT
circuit.cx(0, 1)          # Alias for CNOT
circuit.cz(0, 1)          # Controlled-Z
circuit.swap(0, 1)        # SWAP gate

circuit.toffoli(0, 1, 2)  # Toffoli (CCX)
circuit.ccx(0, 1, 2)      # Alias for Toffoli

​
Backend Comparison

Run the same circuit on all three backends:
backend_comparison.py
from quantum_computer import QuantumComputer, QuantumCircuit, SimulatorConfig

config = SimulatorConfig(device="cpu")
qc = QuantumComputer(config)

# Create GHZ state
circuit = QuantumCircuit(3)
circuit.h(0)
circuit.cnot(0, 1)
circuit.cnot(1, 2)

# Run on all backends
backends = ["hamiltonian", "schrodinger", "dirac"]

print("Comparing backends on 3-qubit GHZ state:")
print("=" * 60)

for backend in backends:
    result = qc.run(circuit, backend=backend)
    prob_000 = result.full_distribution["000"]
    prob_111 = result.full_distribution["111"]
    entropy = result.entropy()
    
    print(f"\n{backend.upper()} Backend:")
    print(f"  P(|000>) = {prob_000:.4f}")
    print(f"  P(|111>) = {prob_111:.4f}")
    print(f"  Entropy  = {entropy:.4f} bits")
Output: 
Comparing backends on 3-qubit GHZ state:
============================================================

HAMILTONIAN Backend:
  P(|000>) = 0.5000
  P(|111>) = 0.5000
  Entropy  = 1.0000 bits

SCHRODINGER Backend:
  P(|000>) = 0.5000
  P(|111>) = 0.5000
  Entropy  = 1.0000 bits

DIRAC Backend:
  P(|000>) = 0.5000
  P(|111>) = 0.5000
  Entropy  = 1.0000 bits
All three backends produce identical results, demonstrating structural consistency in the learned physics representations.

​
Common Use Cases

Algorithm Development

Test quantum algorithms like Grover, QFT, and VQE before deploying to real hardware

Education

Visualize quantum states and measure observables without wavefunction collapse

Molecular Chemistry

Calculate ground state energies for small molecules using VQE with UCCSD ansatz

Benchmarking

Compare neural backend performance against analytical solutions

​
Advanced Features

​
Grover’s Search Algorithm

Run Grover’s algorithm to find a marked state:
grover_example.py
from quantum_computer import QuantumComputer, QuantumCircuit, SimulatorConfig
import math

config = SimulatorConfig(device="cpu")
qc = QuantumComputer(config)

n_qubits = 3
marked_state = 5  # |101>

# Calculate optimal iterations
N = 2 ** n_qubits
optimal_iterations = int(math.pi / 4 * math.sqrt(N))

circuit = QuantumCircuit(n_qubits)

# Initialize superposition
for i in range(n_qubits):
    circuit.h(i)

# Grover iterations
for _ in range(optimal_iterations):
    # Oracle: mark |101>
    circuit.x(1)  # Flip qubit 1
    circuit.h(2)
    circuit.toffoli(0, 1, 2)  # MCZ on marked state
    circuit.h(2)
    circuit.x(1)
    
    # Diffusion operator
    for i in range(n_qubits):
        circuit.h(i)
    for i in range(n_qubits):
        circuit.x(i)
    circuit.h(2)
    circuit.toffoli(0, 1, 2)
    circuit.h(2)
    for i in range(n_qubits):
        circuit.x(i)
    for i in range(n_qubits):
        circuit.h(i)

result = qc.run(circuit, backend="schrodinger")
print(f"Probability of marked state |101>: {result.full_distribution['101']:.4f}")
print(f"Expected: ~0.9453")
Output: 
Probability of marked state |101>: 0.9453
Expected: ~0.9453

​
Next Steps

API Reference

Complete API documentation

Examples

More quantum circuit examples

Advanced Topics

Deep dive into neural backends

​
Troubleshooting

Solution: Ensure you’re using the optimal number of Grover iterations:
optimal_iterations = int(math.pi / 4 * math.sqrt(2**n_qubits))
Solution:
  • Increase --max-iter parameter (default is 100)
  • Check that Hamiltonian construction succeeded (look for ”✓ OpenFermion Hamiltonian verified”)
  • Verify checkpoint files are loaded correctly
Solution: This should not happen! If backends produce different results, check:
  • All checkpoint files are loaded correctly
  • No warnings about “using H-only” fallback
  • Random seed is consistent across runs

​
Resources

  • Source Code: quantum_computer.py - Main simulator implementation (quantum_computer.py:1)
  • Molecular VQE: molecular_sim.py - VQE solver for molecules (molecular_sim.py:1)
  • README: README.md - Full project documentation with research paper
For detailed information about the neural physics backends and validation results, see the Extended Capabilities paper in the README.

Build docs developers (and LLMs) love

Get started for freeTalk to us