API Usage Overview

This page lists public entry points by task, their return forms, and corresponding references. Ordinary circuit workflows import from the unitarylab top level; algorithm and application capabilities are imported from unitarylab.library and its submodules.

Circuits and registers


from unitarylab import Circuit, Register, ClassicalRegister

Task	Entry	Return or behavior	Documentation
Create a circuit	`Circuit(...)`	New `Circuit`	Creating Circuits and Registers
Add gates or circuit measurements	`h()`, `cx()`, `measure()`, etc.	Mutates the circuit	Quantum Gates and Measurement
Copy, invert, or decompose	`copy()`, `inverse()`, `decompose()`, etc.	New `Circuit`	Circuit Transformations
Compose or initialize	`append()`, `prepend()`, `initialize()`	Mutates the circuit	Circuit Transformations

Execution and results

Task	Entry	Return value	Documentation
Pure-state or MPS execution	`Circuit.execute()`	`ExecutionResult`	Executing Circuits and Reading Results
Density-matrix execution	`Circuit.execute_density()`	`DensityMatrixResult`	Density Matrices and Noise Models
Select execution engine and device	`backend`, `device`, `dtype`	Execution configuration	Execution Backends and Parameters
Query probabilities, samples, and expectations	`probability()`, `sample()`, `expectation()`	Scalar, dictionary, or list	Executing Circuits and Reading Results

execute() uses shots for the number of circuit-measurement samples. Terminal-only measurement reuses a single evolution, while mid-circuit measurement executes independently for each shot. ExecutionResult.sample() samples from an existing result distribution; it does not execute the circuit again.

Drawing, analysis, and format conversion

Task	Entry	Return value	Documentation
Draw a circuit	`Circuit.draw()`	Drawing object or text representation	Circuit Analysis and Drawing
Analyze a circuit	`Circuit.analyze()`	`CircuitInfo`	Circuit Analysis and Drawing
Import or export OpenQASM	`from_qasm()`, `to_qasm()`	`Circuit`, string, or file	OpenQASM and Python Import/Export
Generate UnitaryLab/CUDA-Q Python code	`to_python*()`, `to_cudaq()`	String, file, or CUDA-Q kernel	OpenQASM and Python Import/Export

Compilation and hardware


from unitarylab import QCompiler, CompileConfig, CompilationResult, HardwareJob, HardwareResult

Stage	Entry	Return value	Submits a job?
Rule-based optimization	`Circuit.optimize()`	New `Circuit`	No
Gate-basis transpilation	`Circuit.transpile()`	New `Circuit`	No
Mapping and compilation	`Circuit.compile()`	`CompilationResult`	No
Hardware submission	`Circuit.submit()`	`HardwareJob`; `job.result()` queries `HardwareResult`	Yes

See Circuit Optimization and Compilation and Submitting Hardware Jobs for compilation/submission parameters, credentials, and quota risks.

Top-level algorithm entries


from unitarylab.library import (
    QFT, IQFT, QPE, LCU,
    block_encode, hamiltonian_simulation, solve,
    QSVT, QSP, QSP_hamiltonian_simulation,
)

Return form	Entries
`Circuit`	`QFT()`, `IQFT()`, `LCU()`
Circuit or three-element tuple	`QPE()`
Result object	`block_encode()`, `hamiltonian_simulation()`, `solve()`, `QSVT()`
Low-level circuit or tuple	`QSP()`, `QSP_hamiltonian_simulation()`

See Algorithm Library Overview for parameters and result fields.

Application submodules

Task	Module	Main return form
Pauli decomposition and circuit construction	`unitarylab.library.pauli_operator`	List, matrix, or `Circuit`
Fermi–Hubbard utilities	`unitarylab.library.fermi_hubbard`	Dictionary, string, or result object
Ising/QUBO optimization	`unitarylab.library.qubocore`	Dictionary
PDE solving	`unitarylab.library.equation`	Dictionary and generated files
Quantum machine learning	`unitarylab.library.qml`	PyTorch tensors, models, and training records
Quantum chemistry extension	`unitarylab_chemistry`	Staged result object

The corresponding references are Pauli Utilities, Fermi–Hubbard Utilities, QUBO and Ising Solvers, PDE Solver Framework, QML Overview and Backends, and Chemistry Extension.