UnitaryLab Algorithms User Manual

Overview

This manual is intended for developers and researchers using the UnitaryLab Algorithms library (unitarylab_algorithms/). It currently contains 42 algorithm/equation modules across 10 categories. Cryptology, fundamental algorithms, Hamiltonian simulation, linear algebra, quantum chemistry, quantum machine learning, state preparation, search, and quantum transport share unitarylab_algorithms.algo_base.BaseAlgorithm; schrodingerization uses its own unrelated base class and return structure.

With the Algorithms library you can:

Run well-known quantum algorithms such as Shor, Grover, QFT, HHL, VQE, and QAOA with a single .run() call
Automatically save quantum circuit diagrams and algorithm-generated result files; the exact format may be TXT, SVG, PNG, NPY, or QASM depending on the algorithm implementation
Quickly explore algorithm behavior using the preconfigured .test() example functions
Implement custom algorithms based on the provided template

Installation and Version

The Algorithms library is released together with UnitaryLab; to install the full functionality, you need to install both the core package and the algorithms subpackage:


pip install unitarylab
pip install unitarylab-algorithms

After installation, you can confirm the version as follows:


import unitarylab_algorithms
print(unitarylab_algorithms.__version__)

Reading Guide

Scenario	Recommended Reading
First time use, quick start	Quick Start
Understand the full module landscape and API entry points	API Usage Overview
Shor, Simon, discrete logarithm algorithms	Cryptology Algorithms
Grover, QPE, amplitude amplification/estimation, Hadamard	Fundamental Algorithms
Glued trees, hidden shift, quantum-walk search, quantum backtracking	Quantum Search Algorithms
Trotter, QDrift, Taylor, QSP, Cartan	Hamiltonian Simulation
QFT, HHL, LCU, QSP, QSVT, VQLS, AQC	Linear Algebra Algorithms
VQE, VQC, QAOA, QCBM, CVQNN, Fermi-Hubbard VQE	Quantum Machine Learning
2D transverse-field Ising dynamics	Quantum Machine Learning
Molecular electronic structure, DMRG, circuit conversion, measurement	Quantum Chemistry Algorithms
NEGF, transmission, local density of states, and bond current	Quantum Transport
Möttönen, Multiplexer, MPS, Pauli, and other state preparation methods	State Preparation Algorithms
Heat equation, advection equation solvers	Schrödingerization
Writing a new algorithm	Algorithm Template Guide

Module Structure Overview


unitarylab_algorithms/
├── algo_base.py                          # Shared BaseAlgorithm base class
├── template.py                           # Minimal algorithm template
├── cryptology/
│   ├── discrete_log/algorithm.py         # Discrete logarithm algorithm
│   ├── shor/algorithm.py                 # Shor's factoring algorithm
│   └── simon/algorithm.py               # Simon's algorithm
├── fundamental_algorithm/
│   ├── amplitude_amplification/          # Amplitude amplification
│   ├── amplitude_estimation/             # Quantum amplitude estimation
│   ├── grover/                          # Grover's search algorithm
│   ├── hadamard_test/                   # Hadamard test
│   ├── hadamard_transform/              # n-qubit Hadamard transform
│   └── qpe/                            # Quantum phase estimation
├── search/
│   ├── glued_trees/                     # Glued-trees quantum walk
│   ├── hidden_shift/                    # Hidden shift
│   ├── quantum_walk_search/             # Continuous-time quantum-walk search
│   └── quantum_backtracking/            # Quantum backtracking on binary constraint trees
├── hamiltonian_simulation/
│   ├── cartan/                          # Cartan decomposition
│   ├── qdrift/                          # QDrift random product formula
│   ├── qsp/                            # QSP-based Hamiltonian simulation
│   ├── taylor/                         # Taylor series expansion
│   └── trotter/                        # Trotterization
├── linear_algebra/
│   ├── aqc/                             # Adiabatic quantum computing (AQC) linear system solver
│   ├── hhl/                            # HHL linear system solver
│   ├── lcu/                            # Linear combination of unitaries
│   ├── qft/                            # Quantum Fourier transform
│   ├── qsp/                            # QSP polynomial transformation
│   ├── qsvt_qlsa/                      # QSVT-based linear solver
│   └── vqls/                           # Variational quantum linear solver
├── quantum_machine_learning/
│   ├── cvqnn/                          # Continuous-variable quantum neural network
│   ├── fermi_hubbard_vqe/              # VQE ground-state solver for the 1D open Fermi-Hubbard model
│   ├── ising/                           # 2D transverse-field Ising TensorNet dynamics
│   ├── qaoa/                           # Quantum approximate optimization algorithm
│   ├── qcbm/                           # Quantum circuit Born machine
│   ├── vqc/                            # Variational quantum classifier
│   └── vqe/                            # Variational quantum eigensolver
├── quantum_chemistry/
│   └── molecular_dmrg/                  # Electronic structure, DMRG, CVD, and QWC measurement
├── quantum_transport/
│   └── negf/                            # NEGF transport and QSVT lead-injection solving
├── state_preparation/
│   ├── mottonen/                       # Möttönen state preparation
│   ├── multiplexer/                    # Multiplexer state preparation
│   ├── mps/                            # Matrix product state (MPS) preparation
│   ├── pauli/                          # Pauli eigenbasis state preparation
│   └── Superposition/                  # Sparse-support superposition state preparation
└── schrodingerization/
    ├── base.py                          # PDE algorithm base class
    ├── equation_advection/              # 1D advection equation
    ├── equation_heat/                   # 1D heat equation
    └── equation_heat2d/                 # 2D heat equation

Unified Return Format

For algorithms in the nine packages cryptology/fundamental_algorithm/hamiltonian_simulation/linear_algebra/quantum_chemistry/quantum_machine_learning/state_preparation/search/quantum_transport, .run() typically builds its return value via BaseAlgorithm._build_return_dict() (see Algorithm Template Guide), returning a Dict[str, Any] with at least these fields:

Field	Type	Description
`status`	`str`	`'ok'` on success, `'failed'` on failure
`circuit_path`	`str \| list[str]`	Local path to the saved quantum circuit SVG diagram; if multiple circuit diagrams are saved in a single run, this is a list of paths
`plot`	`list[dict]`	Result file info, with each item being `{'format': ..., 'filename': ...}`; `format` is taken from the last 3 characters of the filename
`circuit`	Circuit object or `None`	The raw circuit object passed through by `_build_return_dict()`, for callers that need further processing of the circuit

Note: The schrodingerization package uses an independent base class and a manually constructed return dictionary, with different field shapes (circuit is a list, plot is a single dict) — see Schrödingerization for details.

Some algorithms also return additional algorithm-specific fields (such as factors, phase, fidelity, etc.).