Quick Start

Overview

This chapter will guide you through getting started with the UnitaryLab Algorithms library in 5 minutes. By the end, you will be able to:

• Import an algorithm class and call .run()
• Inspect the returned result dictionary
• Use .test() for a zero-configuration demo
• Locate the saved circuit diagrams and result files

Running Your First Algorithm — Grover’s Search

Grover’s algorithm finds a target in an unsorted database of $2^n$ entries in $O(\sqrt{2^n})$ queries. The example below searches for the state '101' in a 3-qubit register.

from pathlib import Path
from unitarylab_algorithms import GroverAlgorithm
 
 
algo = GroverAlgorithm()
result = algo.run(n=3, target="101")
 
circuit_path = Path(result["circuit_path"])
txt_path = circuit_path.parent / result["plot"][0]["filename"]
 
print(result["status"])        # 'ok'
print(result["circuit_path"])  # path to the SVG circuit diagram
print(txt_path)                # path to the text result file

Expected output:

ok
/path/to/grover_algorithm_circuit.svg
/path/to/grover_algorithm_result.txt

Using .test() for a Quick Demo

The cryptology, fundamental algorithm, Hamiltonian simulation, linear algebra, quantum chemistry, quantum machine learning, state preparation, search, and quantum transport modules generally provide a module-level .test() function that calls .run() with sensible defaults. The three PDE modules under schrodingerization do not define test().

from unitarylab_algorithms.fundamental_algorithm.grover.algorithm import test
test()

test() returns a structured result dictionary and prints the run status to the terminal via internal logging during execution; however, it does not print the returned result dictionary itself in full, and it also saves the circuit diagram and result file locally.

Reading the Result Dictionary

Algorithms in the nine packages cryptology, fundamental_algorithm, hamiltonian_simulation, linear_algebra, quantum_chemistry, quantum_machine_learning, state_preparation, search, and quantum_transport inherit from algo_base.BaseAlgorithm and use _build_return_dict(), so they return a unified dictionary structure:

result = algo.run(n=3, target="101")
 
# Execution status
print(result['status'])         # 'ok' on success
 
# Path to the circuit SVG diagram
print(result['circuit_path'])
 
# Text result file name
print(result["plot"][0]["filename"])

The schrodingerization package uses an independent base class and a manually constructed return dictionary, whose shape differs from the structure above: circuit is a list rather than a single path, and plot is a single dict rather than a list — see the Schrödingerization section for details.

Some algorithms include additional fields. For example, Shor’s algorithm additionally returns:

print(result.get('factors'))    # list of prime factors found

Running Shor’s Algorithm

from unitarylab_algorithms import ShorAlgorithm
 
algo = ShorAlgorithm()
result = algo.run(N=15)
 
print(result['status'])

Running the HHL Linear System Solver

import numpy as np
from unitarylab_algorithms import HHLAlgorithm
 
A = np.array([[0.8, 0], [0, 0.4]])
b = np.array([1, 2])
 
algo = HHLAlgorithm()
result = algo.run(A=A, b=b, d=11)
 
print(result['status'])

Running the Variational Quantum Eigensolver (VQE)

from unitarylab_algorithms import VQEAlgorithm
algo = VQEAlgorithm()
result = algo.run(n=2, layers=2, max_iter=150)
 
print(result['status'])

Running Hidden-Shift Search

from tempfile import TemporaryDirectory
from unitarylab_algorithms.search import HiddenShiftAlgorithm
 
with TemporaryDirectory() as output_dir:
    result = HiddenShiftAlgorithm(algo_dir=output_dir).run(shift="10", shots=32)
    print(result["Matched"])

algo_dir selects the output directory. The temporary directory is deleted when the block exits; use a persistent directory to retain circuit diagrams and results. Backend parameters differ between search algorithms; see Quantum Search Algorithms.

Next Steps