Welcom to Quex

Welcom to Quex#

Quex is a lean, high-throughput quantum execution framework inspired by the Atomic Simulation Environment (ASE). It decouples quantum circuit geometry from the simulation physics, allowing researchers to seamlessly build templates, bind parameters dynamically, and dispatch massive computational batches.

Key Features#

  • ASE-Inspired Architecture: Circuits and Simulators are distinct, attachable objects.

  • Native OpenQASM 3.0: Read, auto-format, and strictly export standard-compliant quantum code.

  • Late-Binding Engine: Designed specifically for high-speed Quantum Machine Learning loops.

  • Hardware-Efficient Ansätze: Generate mathematically rigorous (Haar-uniform) random parameterized circuits instantly.

Check out the Quickstart to get right into the code!

Core Architecture#

  1. The Ingestion Layer: Parses hardware-agnostic formats (OpenQASM 3.0, and eventually QIR) into a lightweight internal Abstract Syntax Tree (AST).

  2. The Dispatcher (WIP): Analyzes circuit depth, qubit count, and host hardware to intelligently route execution.

  3. The Execution Engines (WIP): Wrappers around optimized, low-level linear algebra libraries (NumPy, SciPy Sparse, cuQuantum, etc.) to crunch the matrices efficiently.

        mindmap
  root((quex))
    quex_core((Core))
      Circuit Class
      Gates Registry
      QASM Parser
      ASCII Visualizer
    quex_execution((Execution))
      Simulator Class (Interface)
      Numpy Simulator Class
      Supported Gates
    quex_generative((Generative))
      Random Ansatz Function
    quex_utils((Utils))
      __init__.py
      py.typed (type safety)

Installation and Setup#

Quex is managed using uv, the lightning-fast Python package manager written in Rust.

Prerequisites#

If you don’t have uv installed, we recommend the standalone installer:

curl -LsSf https://astral.sh/uv/install.sh | sh

Local Development Setup#

To clone the repository and set up the development environment instantly:

# 1. Clone the repo
git clone https://github.com/rajarshitiwari/quex.git
cd quex

# 2. Sync dependencies (uv will automatically create a .venv and install the lockfile)
uv sync

# 3. (Optional) Run tests to ensure everything is working
uv run pytest

💻 Quick Start#

Currently, Quex features a highly efficient (hopefully) parsing layer for OpenQASM 3.0 strings. Here is how to ingest a standard quantum circuit:

import quex as qx

# 1. Define the geometry (The "Atoms" equivalent)
qc = qx.Circuit(num_qubits=2)

# 2. Add standard operations
qc.add_operation('h', 0)
qc.add_operation('cx', [0, 1])

# 3. Quex features a built-in topological visualizer
print("Circuit Topology:")
print(qc)

Circuit Topology:
q[0]: ───[H]───■───
               │   
q[1]: ─────────X───

More detailed, quickstart tutorial is available at Quickstart.

Running Scripts Locally#

Because uv handles virtual environments automatically, you do not need to manually activate your .venv. Simply prepend uv run to execute your scripts with all Quex dependencies loaded:

uv run your_script.py

🗺️ Roadmap#

  • [x] OpenQASM 3.0 Ingestion Layer

  • [x] Internal Circuit Representation

  • [x] Baseline Classical Execution Engine (NumPy state-vector simulation)

  • [ ] Hardware Dispatcher Logic

  • [ ] Advanced Execution Engines (SciPy Sparse, cuQuantum integration)

  • [ ] LLVM-based QIR Ingestion