API Usage Overview

Overview

This page is a navigation guide for the unitarylab_algorithms/ library, summarizing the class names, import paths, key parameters, and .test() signatures of all available algorithms.

This page is not a complete auto-generated API reference. Its purpose is to help you quickly locate the algorithm you need and understand how to call it.

BaseAlgorithm — Shared Base Class

The algorithm classes in the nine packages cryptology, fundamental_algorithm, hamiltonian_simulation, linear_algebra, quantum_chemistry, quantum_machine_learning, state_preparation, search, and quantum_transport inherit from unitarylab_algorithms.algo_base.BaseAlgorithm. schrodingerization uses its own base class and return shape; see Schrödingerization.

The shared base class does not create algo_dir. A class that inherits from it directly must supply and create a writable directory before calling save_circuit() or save_txt(); each current algorithm subclass fills in its own default result directory and calls os.makedirs(..., exist_ok=True) in __init__(). In addition, the filepath passed to _build_return_dict() must be a string or an iterable of filenames, not None.

Algorithm Index by Category

Cryptology

Fundamental Quantum Algorithms

Quantum Search

All four classes can be imported from unitarylab_algorithms.search or the root package and inherit from the shared BaseAlgorithm. See Quantum Search Algorithms for complete parameters, examples, and return fields.

Hamiltonian Simulation

Linear Algebra

Quantum Machine Learning

IsingAlgorithm is exported by its category package and included in the root __all__, so it can be imported directly by name. See Quantum Machine Learning.

Quantum Chemistry

MolecularDMRGAlgorithm is included in the root __all__ and may be imported with from unitarylab_algorithms import MolecularDMRGAlgorithm. It requires the separate Chemistry package and supports Linux/macOS only. See Quantum Chemistry Algorithms.

Quantum Transport

NEGFAlgorithm is included in the root __all__ and can also be imported from unitarylab_algorithms.quantum_transport. run() does not accept backend, device, or dtype; it uses NumPy on CPU with np.complex128 internally. Execution requires Kwant. See Quantum Transport for parameters, return values, and QASM export limits.

State Preparation

See State Preparation Algorithms for details, which includes 9 package-level discrepancy notes such as the backend/device/dtype parameters, and inconsistencies between the target_error default value and parameters.json (MPS, Superposition).

Schrödingerization (PDE Solvers)

.test() Quick Reference

Most algorithm modules provide a standalone test() function that can be used to quickly run a default example or verify that the algorithm is available:

# Run using built-in defaults — no need to instantiate the class
from unitarylab_algorithms.fundamental_algorithm.grover.algorithm import test
test()
 
from unitarylab_algorithms.cryptology.shor.algorithm import test
test(N=15, method='matrix', max_retries=15)
 
from unitarylab_algorithms.linear_algebra.hhl.algorithm import test
test(A=[[0.8, 0], [0, 0.4]], b=[1, 2], d=11)
 
from unitarylab_algorithms.quantum_machine_learning.vqe.algorithm import test
test(n=2, layers=2, max_iter=150)
 
from unitarylab_algorithms.state_preparation.mottonen.algorithm import test
test(Psi=[1, 0, 0, 1], target_qubits=2, target_error=1e-6)
 
from unitarylab_algorithms.quantum_machine_learning.ising.algorithm import test
test(rows=2, cols=2, trotter_steps=2, local_configuration_mode="none")
 
from unitarylab_algorithms.quantum_chemistry.molecular_dmrg.algorithm import test
test(xyz_file="H2")  # runs the complete, heavyweight Chemistry workflow

Common Usage Patterns

Passing a Circuit Object

Algorithms such as QPE, LCU, and Amplitude Amplification accept a Circuit object from unitarylab:

from unitarylab.core import Circuit
from unitarylab_algorithms import QPEAlgorithm
 
# Build a unitary circuit whose phase we want to estimate
U = Circuit(1)
U.t(0)  # T gate has phase π/4
 
algo = QPEAlgorithm()
result = algo.run(U=U, d=4)

Passing a Hamiltonian Matrix

Hamiltonian simulation algorithms accept a NumPy array or a 2D Python list:

import numpy as np
from unitarylab_algorithms import TrotterAlgorithm
 
H = np.array([[2, 1], [1, 3]])
algo = TrotterAlgorithm()
result = algo.run(H=H, t=1.0, error=1e-8, order=1, steps=1000)