TyxonQ

A Modular Full-stack Quantum Software Framework on Real Machine

For Chinese Introduction, see: 中文README. For Japanese Introduction, see: 日本語README.

TyxonQ (太玄量子) is a production-ready, next-generation quantum programming framework featuring stable IR, pluggable compiler, unified device abstraction (simulators and hardware), single numerics backend interface (NumPy/PyTorch/CuPyNumeric), and device-runtime friendly postprocessing. Version 1.0.0 introduces revolutionary pulse-level control, China Mobile QCOS (Quantum Computing OS) integration, and enhanced quantum chemistry performance.

Core goals

• System‑architect‑friendly, hardware‑realistic programming model: stable IR + chain pipeline mirroring real device execution; clear contracts for compiler, devices, and postprocessing; closest‑to‑hardware code path.

• Quantum AIDD (Quantum Computational Chemistry for advanced AI Drug Design): PySCF‑like UX, hardware‑realistic execution; familiar molecule/ansatz APIs route to device or numerics without code changes. Mission: prioritize drug design—provide missing microscopic Quantum Chemistry data and robust computational tools for AI drug discovery; roadmap includes drug design–oriented Hamiltonians, method optimization, and AI‑for‑QC.

• Dual paths: Hamiltonians, measurement grouping, shot planning, device execution (shots/noise) and exact numerics (statevector/MPS) with shared semantics.

• Extensible domain layer: algorithms and chem libs are modular for specialized extensions.

Try Real Quantum Computer Right Now！: Getting a Key to register and obtain your API key. Directly use the TyxonQ cloud task submission API. For details, see the example: examples/cloud_api_task.py

Quick start

Minimal circuit → simulator / hardware

import tyxonq as tq
from tyxonq.libs.quantum_library.kernels import quantum_info
import getpass
tq.set_backend("numpy")

# Configure quantum hardware access
#API_KEY = getpass.getpass("Input your TyxonQ API_KEY:")
#tq.set_token(API_KEY) # Get from https://www.tyxonq.com

# Build once
c = tq.Circuit(2).h(0).cx(0, 1).measure_z(0).measure_z(1)

# Simulator path
sim = (
    c.compile()
     .device(provider="simulator", device="statevector", shots=4096)
     .postprocessing(method=None)
     .run()
)

# Hardware path (example target)
hw = (
    c.compile(output="qasm")
     .device(provider="tyxonq", device="homebrew_s2", shots=4096)
     .run()
)

def counts_of(res):
    payload = res if isinstance(res, dict) else (res[0] if res else {})
    return payload.get("result", {})

ez_sim = metrics.expectation(counts_of(sim), z=[0, 1])
ez_hw  = metrics.expectation(counts_of(hw),  z=[0, 1])
print("E[Z] (sim)", ez_sim)
print("E[Z] (hw) ", ez_hw)

Pulse-Level Quantum Control

import tyxonq as tq
from tyxonq import waveforms

# High-level: Write algorithms with gates
circuit = tq.Circuit(2).h(0).cx(0, 1)

# Hardware execution: Automatic TQASM export for real QPU
result = circuit.device(provider="tyxonq", device="homebrew_s2").run(shots=1024)

# Or use China Mobile QCOS hardware
result = circuit.device(
    provider="qcos",
    device="WuYue-QPUSim-FullAmpSim",
    shots=1024,
    access_key="your_access_key",
    secret_key="your_secret_key"
).run()

Minimal Quantum Chemistry (PySCF‑style)

# pip install pyscf  # required for UCCSD example
import tyxonq as tq
from tyxonq.applications.chem import UCCSD
from tyxonq.applications.chem import molecule

tq.set_backend("numpy")

# Preset H2 molecule (RHF defaults handled inside UCCSD)
ucc = UCCSD(molecule.h2)

# Device chain on simulator (counts → energy)
e = ucc.kernel(shots=2048, provider="simulator", device="statevector")
# Device chain on real machine (counts → energy)
#e = ucc.kernel(shots=2048, provider="tyxonq", device="homebrew_s2")
print("UCCSD energy (device path):", e)

Installation

pip install tyxonq
# or from source
uv build && uv pip install dist/tyxonq-*.whl

# For China Mobile QCOS integration (requires Python 3.11)
# Download the unified WuYue SDK whl from the ecloud console
# (Programming Framework -> SDK Local Deployment) and install it:
pip install wuyue-1.0-py3-none-any.whl
# Then reinstall tyxonq from source

🔑 Quantum Hardware Setup

Getting API Access

1. Apply for API Key: Visit TyxonQ Quantum AI Portal to register and obtain your API key
2. Hardware Access: Request access to Homebrew_S2 quantum processor through API TyxonQ QPU API
3. China Mobile QCOS: For ecloud quantum hardware access, visit China Mobile ecloud console and setup your account

Hardware API Configuration

Set up your API credentials:

import tyxonq as tq
import getpass

# Configure TyxonQ quantum hardware access
API_KEY = getpass.getpass("Input your TyxonQ API_KEY:")
tq.set_token(API_KEY) # Get from https://www.tyxonq.com

# Configure China Mobile QCOS (alternative)
# Credentials can be set via environment variables:
# export QCOS_ACCESS_KEY="your_access_key"
# export QCOS_SECRET_KEY="your_secret_key"

Supported Hardware Providers

Provider	Device Type	Access Method
TyxonQ	homebrew_s2	Direct API access
QCOS	WuYue-* series	China Mobile ecloud plugin
Quafu	Dongling, Baihua, ...	BAQIS Quafu superconducting cloud. Token from https://quafu-sqc.baqis.ac.cn/. See docs/quafu_provider.md.
LQCloud	Account-visible devices	LogicalQubit cloud via the official lqcloud SDK. See docs/lqcloud_provider.md.
Guodun	gd_* series	QuantumCTek cloud via QCIS and cqlib. See docs/guodun_provider.md.
Simulators	statevector, density_matrix, mps	Local execution

AI Agent & MCP Integration

TyxonQ can be integrated with AI agent workflows through MCP (Model Context Protocol).

The OpenQuantum project provides a TyxonQ local simulation workbench, including:

• TyxonQ SDK integration through MCP tools
• Agent Skill definitions for automated quantum circuit workflows
• Local quantum circuit simulation with TyxonQ backend

Project:

• OpenQuantum: https://github.com/xi-zhao/openQuantum

This integration enables AI agents to interact with TyxonQ through structured tools while maintaining controlled and reproducible quantum execution workflows.

📖 Technical Documentation

TyxonQ Technical Whitepaper

For developers, researchers, and engineers interested in the deep technical architecture and innovations of TyxonQ, we strongly recommend reading our comprehensive technical whitepaper:

📋 TYXONQ_TECHNICAL_WHITEPAPER.md

This document provides:

• Novel architectural innovations: Dual-path execution model, compiler-driven measurement optimization, and stable IR design
• Quantum AIDD technical details: AI-driven drug discovery applications with hardware-realistic quantum chemistry stack
• System design principles: Cross-vendor portability, counts-first semantics, and single numeric backend abstraction
• Academic-quality analysis: Comprehensive comparison with existing frameworks and research directions
• Implementation details: Core components, execution flows, and integration patterns

Architecture

Key features

• Chain API: Circuit.compile().device(...).postprocessing(...).run().

• Two-layer compiler (refactored in v1.4): a device-agnostic gate_compiler core assembles a typed step pipeline — normalize → decompose (matchgate/rotations) → route → optimize → simplify (light‑cone) — while per-hardware platforms/* dialects (tyxonq/lqcloud/guodun) delegate to the core, then translate to their native format, so no compilation logic is duplicated per vendor.

  • Routing: SABRE layout + SWAP insertion delegated to qiskit.transpile, run in a local index space with a reproducible seed and measurement-order preservation; the source IR is never rewritten.
  • Clean layering: exporters/ = pure zero-dependency QASM2/QASM3 text; interop/ = IR ↔ Qiskit QuantumCircuit and tensor-network MPO; platforms/ = hardware dialects. Qiskit is now an interop target, not a pseudo hardware platform.
  • Fix: output="qasm2" now emits a real OpenQASM 2.0 string instead of silently falling back to IR (benefits homebrew_s2/quafu submission).

• Devices: statevector/density‑matrix/MPS simulators and hardware drivers (e.g., tyxonq:homebrew_s2).

• Numerics: one ArrayBackend for NumPy/PyTorch/CuPyNumeric powering simulators and research kernels.

• Libraries: libs/circuits_library (templates: VQE/QAOA/trotter/state‑prep), libs/quantum_library (numeric kernels), libs/hamiltonian_encoding (OpenFermion I/O, encodings), libs/optimizer (interop).

• Real Quantum Hardware Ready: TyxonQ supports real quantum machine execution through our quantum cloud services powered by QureGenAI. Currently featuring the Homebrew_S2 quantum processor, enabling you to run your quantum algorithms on actual quantum hardware, not just simulators.

• 🎯 Industry-Leading Pulse Programming: TyxonQ features the most comprehensive pulse-level quantum control framework:

  • Dual-Mode Architecture: Chain compilation (Gate→Pulse→TQASM) + Direct Hamiltonian evolution
  • Dual-Format Support: Native pulse_ir (PyTorch autograd enabled) + TQASM 0.2 (cloud-compatible)
  • 10+ Waveform Types: DRAG, Gaussian, Hermite, Blackman, with physics-validated implementations
  • Hardware-Realistic Physics: Cross-Resonance gates, Virtual-Z optimization, T1/T2 noise models
  • Complete QASM3+OpenPulse: Full support for defcal, frame operations, and pulse scheduling
  • Cloud-Ready: Seamless local simulation → real QPU deployment with TQASM export

• Quantum API Gateway: RESTful APIs for direct quantum hardware access

• ☁️ Quantum Cloud Services: Scalable quantum computing as a service

🚀 Performance Leadership

TyxonQ delivers industry-leading performance in gradient computation and quantum chemistry workflows:

Framework	Time/Step	Method
TyxonQ (PyTorch + Autograd)	0.012s	Automatic differentiation
PennyLane (default.qubit)	0.0165s	Backpropagation
Qiskit (Estimator)	0.0673s	Finite differences

Benchmark: LiH molecule VQE (4 qubits, 10 parameters), measured on M2 MacBook Pro

Key Performance Advantages:

• ✨ PyTorch Autograd: Complete automatic differentiation support with gradient chain preservation
• 🎯 Multi-Backend Architecture: Seamless switching between NumPy/PyTorch/CuPy without code changes
• 🔬 Optimized Implementation: Efficient gradient computation through proper autograd integration
• 📊 Production-Ready: Validated on VQE benchmarks with H₂, LiH, BeH₂ molecules

🎛️ Pulse-Level Quantum Control: The Last Mile to Real Hardware

TyxonQ's pulse programming capabilities represent the most complete pathway from gate-level algorithms to real quantum hardware execution:

Why Pulse-Level Control Matters

While most quantum frameworks stop at gate-level abstraction, real quantum computers execute electromagnetic pulses, not abstract gates. This "last mile" translation is where TyxonQ excels:

import tyxonq as tq
from tyxonq import waveforms

# High-level: Write algorithms with gates
circuit = tq.Circuit(2).h(0).cx(0, 1)

# Mid-level: Compile gates to physics-realistic pulses
circuit.use_pulse(device_params={
    "qubit_freq": [5.0e9, 5.1e9],
    "anharmonicity": [-330e6, -320e6]
})

# Hardware execution: Automatic TQASM export for real QPU
result = circuit.device(provider="tyxonq", device="homebrew_s2").run(shots=1024)

Unique Pulse Programming Features

1. Dual-Mode Architecture

• Mode A (Chain): Gate Circuit → Pulse Compiler → TQASM → QPU - Automatic gate decomposition
• Mode B (Direct): Hamiltonian → Schrödinger Evolution → State - Physics-based simulation

2. Physics-Validated Gate Decompositions

TyxonQ implements hardware-realistic gate decompositions based on peer-reviewed research:

Gate	Pulse Decomposition	Physical Basis
X/Y Gates	DRAG pulses	Derivative removal suppresses
Z Gates	Virtual-Z	Zero-time phase updates in software (McKay et al., PRA 2017)
CX Gate	Cross-Resonance	σ_x ⊗ σ_z interaction (Magesan & Gambetta, PRB 2010)
H Gate	RY(π/2) · RX(π)	Two-pulse composite sequence
iSWAP/SWAP	Native pulse sequences	Direct qubit-qubit coupling

3. Complete Waveform Library

TyxonQ provides 10+ waveform types with full hardware compatibility:

from tyxonq import waveforms

# DRAG pulse - industry standard for single-qubit gates
drag = waveforms.Drag(
    amp=0.8,        # Amplitude
    duration=40,    # 40 nanoseconds
    sigma=10,       # Gaussian width
    beta=0.18       # Leakage suppression coefficient
)

# Hermite pulse - smooth envelope for high-fidelity gates
hermite = waveforms.Hermite(
    amp=1.0,
    duration=160,
    order=3         # 3rd-order polynomial
)

# Blackman window - optimal time-frequency characteristics
blackman = waveforms.BlackmanSquare(
    amp=0.9,
    duration=200,
    rise_fall_time=20
)

4. Three-Level System Support

Unlike gate-only frameworks, TyxonQ models realistic transmon qubits as 3-level systems:

# Simulate leakage to |2⟩ state with 3-level dynamics
result = circuit.device(
    provider="simulator",
    three_level=True  # Enable 3×3 Hamiltonian evolution
).run(shots=2048)

leakage = result[0].get("result", {}).get("2", 0) / 2048
print(f"Leakage to |2⟩: {leakage:.4f}")  # Typical: < 1% with DRAG

5. TQASM 0.2 + OpenPulse Export

TyxonQ generates industry-standard TQASM with full defcal support:

# Compile to TQASM for cloud execution
compiled = circuit.compile(output="tqasm")
print(compiled._compiled_source)

# Output:
# OPENQASM 3.0;
# defcal rx(angle[32] theta) q { ... }
# defcal cx q0, q1 { ... }
# gate h q0 { rx(pi/2) q0; }
# qubit[2] q;
# h q[0];
# cx q[0], q[1];

Framework Comparison: Pulse Capabilities

Feature	TyxonQ	Qiskit Pulse	QuTiP-qip	Cirq
Gate→Pulse Compilation	✅ Automatic	✅ Manual	✅ Automatic	❌ Limited
Waveform Library	✅ 10+ types	✅ 6 types	✅ 5 types	❌ 2 types
3-Level Dynamics	✅ Full support	❌ 2-level only	✅ Full support	❌ 2-level only
PyTorch Autograd	✅ Native	❌ No	❌ No	❌ No
TQASM/QASM3 Export	✅ Full defcal	✅ Qiskit format	❌ No	✅ Limited
Cross-Resonance CX	✅ Physics-based	✅ Yes	✅ Yes	❌ No
Virtual-Z Gates	✅ Zero-time	✅ Yes	❌ No	❌ No
Cloud QPU Ready	✅ TQASM export	✅ IBM only	❌ Local only	✅ Google only

Real-World Validation

Bell State Fidelity with Realistic Noise:

# Test: CX gate fidelity under T1/T2 relaxation
circuit = tq.Circuit(2).h(0).cx(0, 1)

# Hardware-realistic parameters
result = circuit.use_pulse(device_params={
    "T1": [50e-6, 45e-6],      # Amplitude damping
    "T2": [30e-6, 28e-6],      # Phase damping
    "gate_time": 200e-9        # CX gate duration
}).run(shots=4096)

# Measured fidelity: 0.97 (matches IBM Quantum hardware)

Pulse Optimization with PyTorch:

import torch

# Optimize pulse amplitude for maximum fidelity
amp = torch.tensor([1.0], requires_grad=True)
optimizer = torch.optim.Adam([amp], lr=0.01)

for step in range(100):
    pulse = waveforms.Drag(amp=amp, duration=160, sigma=40, beta=0.2)
    # ... circuit construction with optimized pulse ...
    fidelity = compute_fidelity(result, target_state)
    loss = 1 - fidelity
    loss.backward()  # Automatic gradient through pulse physics!
    optimizer.step()

Why TyxonQ Leads in Pulse Programming

1. Seamless Abstraction Bridging: Write high-level algorithms, get hardware-ready pulses automatically
2. Physics Fidelity: Validated against peer-reviewed models (QuTiP-qip, IBM research)
3. Hardware Portability: Same code runs on TyxonQ QPU, IBM Quantum, or local simulators
4. Optimization Ready: PyTorch autograd enables pulse-level variational algorithms
5. Production Tested: All features verified on real superconducting qubits

Learn More:

• 📖 Complete guide: PULSE_MODES_GUIDE.md
• 🎓 Tutorial: examples/pulse_basic_tutorial.py
• 🔬 Technical details: PULSE_PROGRAMMING_SUMMARY.md

✨ Advanced Quantum Features

Automatic Differentiation

import tyxonq as tq
import torch

# PyTorch autograd automatically tracks gradients
tq.set_backend("pytorch")
params = torch.randn(10, requires_grad=True)

def vqe_energy(p):
    circuit = build_ansatz(p)
    return circuit.run_energy(hamiltonian)

energy = vqe_energy(params)
energy.backward()  # Automatic gradient computation
print(params.grad)  # Gradients ready for optimization

Quantum Natural Gradient (QNG)

from tyxonq.compiler.stages.gradients.qng import compute_qng_metric

# Fubini-Study metric for quantum optimization
metric = compute_qng_metric(circuit, params)
natural_grad = torch.linalg.solve(metric, grad)
params -= learning_rate * natural_grad

Time Evolution with Trotter-Suzuki

from tyxonq.libs.circuits_library.trotter_circuit import build_trotter_circuit

# Hamiltonian time evolution
H = build_hamiltonian("HeisenbergXXZ")
circuit = build_trotter_circuit(H, time=1.0, trotter_steps=10)
result = circuit.run(shots=2048)

Production-Ready Noise Simulation

# Realistic noise models for NISQ algorithms
circuit = tq.Circuit(2).h(0).cx(0, 1)

# Depolarizing noise
result = circuit.with_noise("depolarizing", p=0.05).run(shots=1024)

# T1/T2 relaxation (amplitude/phase damping)
result = circuit.with_noise("amplitude_damping", gamma=0.1).run(shots=1024)
result = circuit.with_noise("phase_damping", l=0.05).run(shots=1024)

Quantum AIDD Key features

• Algorithms: HEA and UCC family (UCC/UCCSD/k‑UpCCGSD/pUCCD) with consistent energy/gradient/kernel APIs.

• Runtimes: device runtime forwards grouped measurements to postprocessing; numeric runtime provides exact statevector/civector (supports PyTorch autograd).

• Hamiltonians: unified sparse/MPO/FCI‑function outputs; convenient molecule factories (applications/chem/molecule.py).

• Measurement and shots: compiler‑driven grouping and shot scheduling enable deterministic, provider‑neutral execution.

• Properties: RDM1/2 and basic property operators; dynamics numeric path caches MPO/term matrices to avoid rebuilds.

• Bridges: OpenFermion I/O via libs/hamiltonian_encoding; tight interop with PySCF for references and integrals.

• Module layout (refined in v1.3.0): applications/chem/ is organized by domain — algorithms/vqe/ (UCC family + HEA, with runtimes/ device/numeric backends and a wavefunction/ CI/statevector library), dynamics/ (time-evolution evolution.py + models/{pyrazine,sbm}), hamiltonian_builders.py (HF/integrals → Hamiltonians), and interfaces/ (MD/QM-MM). Public API unchanged: from tyxonq.applications.chem import UCCSD, HEA, ....

• MD / QM-MM ecosystem (v1.2.0): applications/chem/interfaces/ plugs TyxonQ into molecular-dynamics engines as the QM force provider — qc_scanner (energy/gradient facade with cluster and periodic Ewald electrostatic embedding, per-step environment update, MM back-reaction forces), TyxonQCalculator (ASE, region partitioning), TyxonQDriver (i-PI), OpenMM native QM/MM (create_tyxonq_system / create_qmmm_ee_system), and TyxonQMdiEngine (MDI dedicated line). All gradients are reused from PySCF; QM backends selectable via method="uccsd" | "hea" | ..., with HEA execution options (shots/provider/device) forwarded to simulators or real quantum hardware. 👉 See examples/qmmm/ for 10 runnable tutorials (E1–E10; E10 targets simulators/real quantum hardware).

• AIDD (AI Drug Design) field Feature

  • Drug‑design‑oriented Hamiltonians and workflows (ligand–receptor fragments, solvent/embedding, coarse‑grained models) prioritized for AI Drug Design.
  • Method optimization for AIDD tasks: tailored ansatz/measurement grouping, batched parameter‑shift/QNG, adaptive shot allocation.
  • AI‑for‑QC bridges: standardized data schemas and export of Quantum Chemistry field data (energies, RDMs, expectations,ansatz,active space,etc) for QC algorithms development.
  • Expanded properties and excited states (VQD/pVQD) aligned with spectroscopy and binding‑relevant observables.

📚 Comprehensive Example Library

TyxonQ includes 80+ high-quality examples covering:

• Variational Algorithms: VQE, QAOA, VQD with SciPy/PyTorch optimization
• Quantum Chemistry: UCCSD, k-UpCCGSD, molecular properties (RDM, dipole, HOMO-LUMO gaps)
• QM/MM & Molecular Dynamics (new in v1.2.0): qc_scanner-based ab-initio MD, ASE optimization, i-PI driver, LAMMPS three-process QM/MM (cluster + periodic Ewald), OpenMM QM/MM with electrostatic embedding, MDI dedicated line — see examples/qmmm/
• Pulse-Level Control: Gate→Pulse compilation, waveform design, TQASM export
• Quantum Machine Learning: MNIST classification, hybrid GPU training
• Advanced Techniques: Quantum Natural Gradient, Trotter evolution, slicing
• Noise Simulation: T1/T2 calibration, readout mitigation, error analysis
• Performance Benchmarks: Framework comparisons, optimization strategies
• Hardware Deployment: Real quantum computer execution examples (TyxonQ + QCOS)
• Research Projects: GQE drug design transfer learning, AIDD workflows

Explore the full collection in examples/ directory.

Dependencies

• Python >= 3.10 (supports Python 3.10, 3.11, 3.12+)
• PyTorch >= 1.8.0 (required for autograd support)
• For QCOS integration: Python 3.11 required

📧 Contact & Support

• Home: www.tyxonq.com
• Technical Support: code@quregenai.com
• General Inquiries: bd@quregenai.com
• Issue: github issue
• Documentation: Technical Whitepaper

微信公众号 | Official WeChat

开发者交流群 | Developer Community

扫码关注公众号获取最新资讯 | Scan to follow for latest updates
扫码加入开发者群进行技术交流 | Scan to join developer community

Development Team

• QureGenAI: Quantum hardware infrastructure and services
• TyxonQ Core Team: Framework development and optimization
• Community Contributors: Open source development and testing

License

TyxonQ is open source, released under the Apache License, Version 2.0.