UnitaryLab Algorithms User Manual

Overview

This manual is intended for developers and researchers who want to run quantum algorithms using the UnitaryLab Algorithms library (unitarylab_algorithms/). The cryptology, fundamental algorithm, Hamiltonian simulation, linear algebra, quantum machine learning, and state preparation algorithms share the unitarylab_algorithms.algo_base.BaseAlgorithm interface, providing a unified workflow for execution, logging, and result export; schrodingerization uses an independent schrodingerization.base.BaseAlgorithm interface with no inheritance relationship to the former, and its parameters and return structure differ.

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, or NPY 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
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
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
├── 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
│   ├── qaoa/                           # Quantum approximate optimization algorithm
│   ├── qcbm/                           # Quantum circuit Born machine
│   ├── vqc/                            # Variational quantum classifier
│   └── vqe/                            # Variational quantum eigensolver
├── 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 six packages cryptology/fundamental_algorithm/hamiltonian_simulation/linear_algebra/quantum_machine_learning/state_preparation, the .run() method typically builds its return value via BaseAlgorithm._build_return_dict() (see Algorithm Template Guide for details), returning a Dict[str, Any] that contains at least the following 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.).