UnitaryLab Simulator User Manual

UnitaryLab provides Python interfaces for quantum-circuit construction, simulation, circuit analysis, format conversion, compilation, and algorithms. This manual is for developers using these public interfaces.

Scope

Task	Main entry points	Documentation
Create circuits, registers, and gates	`Circuit`, `Register`, `ClassicalRegister`	Circuit Basics
Execute pure-state circuits and read results	`Circuit.execute()`, `ExecutionResult`	Circuit Execution
Simulate density matrices and gate-after noise	`Circuit.execute_density()`	Density Matrices and Noise Models
Draw, analyze, and exchange circuits	`draw()`, `analyze()`, `to_qasm*()`, `to_python()`, `to_cudaq()`	Circuit Tools
Optimize, transpile, and map circuits	`optimize()`, `transpile()`, `compile()`	Circuit Optimization and Compilation
Submit jobs to real quantum hardware	`submit()`, `QCompiler.submit()`	Submitting Hardware Jobs
Use algorithms and application utilities	`unitarylab.library` and submodules	Algorithm Library Overview
Run molecular electronic-structure and DMRG workflows	`unitarylab_chemistry`	Chemistry Extension

Installation

Supported Python versions are 3.10–3.12. The main simulator supports Windows, Linux, and macOS:


pip install unitarylab


import unitarylab
print(unitarylab.__version__)

Optional components:


# CUDA 12 C++ backend
pip install "unitarylab[cuda]"
 
# Chemistry extension
pip install "unitarylab[chemistry]"

The CUDA extra installs the unitarylab-cu12 wheel matching the current Python and platform and requires a compatible NVIDIA driver at runtime. The Chemistry extension supports Linux and macOS, not Windows; this limitation does not affect the main simulator.

Core entry points


from unitarylab import Circuit, Register, ClassicalRegister

Circuit: stores gates, measurement mappings, and registers, and provides execution, drawing, export, and compilation methods.
Register: defines a quantum register.
ClassicalRegister: defines a classical register used by circuit measurements.
QCompiler: provides optimization, transpilation, mapping, and hardware-submission pipelines.
unitarylab.library: provides core algorithms and application utilities.

See API Usage Overview for import paths and return forms.

Terms

Term	Meaning
backend	Implementation of state representation and gate operations, such as `torch`, `numpy`, `cpp`, or `tensornet`
shots	Number of circuit-measurement samples; circuits with mid-circuit measurement execute independently for each shot
classical	A branch using classical numerical methods that does not construct a quantum execution result
block encoding	A method of embedding a non-unitary matrix, up to a scale factor, in a larger unitary matrix

Reading path

Quick Start: create and execute a Bell-state circuit.
API Usage Overview: select public entry points by task.
Circuit Basics: learn registers, gates, and circuit transformations.
Circuit Execution: read states, probabilities, samples, and measurement results.
Algorithm Library Overview: select algorithms and application modules.