API Usage Overview

This page is a navigation guide to the UnitaryLab simulator API, describing the responsibilities of each module and the recommended reading order. This page is not a complete API Reference — for function signatures and parameter details, refer to each chapter’s documentation.

Recommended Import


from unitarylab import Circuit, Register, ClassicalRegister

Circuit is the starting point for all operations. The top level of the unitarylab package exports only three names — Circuit, Register, and ClassicalRegister (from unitarylab.core import ... is an equivalent form); backend, circuit_analysis, drawer, transpiler, and codegen only need to be used directly for debugging, extension, or performance tuning. The algorithm library unitarylab.library independently exports a set of high-level algorithm functions, described below.

Module Layers


unitarylab/
├── core/               # User-facing layer: Circuit, Register, ClassicalRegister
├── backend/            # Internal implementation layer: gate structures, gate sequences, executors, tensor networks, QASM, low-level gate matrices
├── transpiler/         # Circuit transpilation: gate-basis decomposition and optimization rules
├── codegen/            # Circuit → Python source code generation
├── circuit_analysis/   # Circuit static analysis: CircuitInfo
├── drawer/             # Circuit drawing: CircuitDrawer (mpl / text / latex)
└── library/            # Algorithm library: QFT, QPE, LCU, QSP, QSVT, block encoding, Hamiltonian simulation, linear system solving, etc.

Core Documentation Pages

Core Circuit Interface

The complete reference for circuit construction, including:

Creating a Circuit, and using Register / ClassicalRegister
Single-qubit gates (h, x, rx, rz, etc., all of which support broadcasting to multiple qubits at once) and two-qubit gates (cx, swap)
Controlled gates (including multi-controlled versions mcx/mcy/mcz/mch/mcp/mcrx/mcry/mcrz), custom unitary-matrix gates, and circuit transformations (inverse(), reverse(), repeat(), decompose(), control(), append()/prepend(), etc.)
measure operations and classical registers
OpenQASM 2.0 / 3.0 and Python source code import/export (to_qasm(), from_qasm(), to_python())

Circuit Workflow

The comprehensive reference for executing circuits and the accompanying tools, including:

Circuit.execute() and ExecutionResult (state, probabilities, expectation(), sample(), classical_results_map, counts)
The backend, device, dtype, shots, seed, and backend_options parameters
qc.draw() for drawing and CircuitInfo / qc.analyze() for circuit analysis
OpenQASM export (Circuit.to_qasm() / to_qasm2()) and import (Circuit.from_qasm())

Algorithms and Utility Library

Built-in algorithm modules, including:

Algorithm	Import path
QFT / IQFT	`from unitarylab.library import QFT, IQFT`
QPE	`from unitarylab.library import QPE`
LCU	`from unitarylab.library import LCU`
Block encoding	`from unitarylab.library import block_encode`
Unified Hamiltonian simulation entry point	`from unitarylab.library import hamiltonian_simulation`
Unified linear system solving entry point	`from unitarylab.library import solve`
QSVT (scalar function transformation)	`from unitarylab.library import QSVT`
QSP / QSP Hamiltonian simulation	`from unitarylab.library import QSP, QSP_hamiltonian_simulation`

The 10 names above are the entire set of names exported directly from the top level of the unitarylab.library package (i.e., the __all__ of library/__init__.py). Lower-level method classes (such as Trotter, QDrift, HHL, VQLS, etc.) need to be imported from their corresponding submodules — see Algorithms and Utility Library for details.