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 machine learning, and state preparation modules generally provide a module-level .test() function that calls .run() with sensible built-in default parameters — the fastest way to observe typical output. However, not all algorithms provide this function — the 3 partial differential equation algorithm modules under the schrodingerization package (equation_advection, equation_heat, equation_heat2d) 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 six packages cryptology, fundamental_algorithm, hamiltonian_simulation, linear_algebra, quantum_machine_learning, and state_preparation all inherit from algo_base.BaseAlgorithm and build their return values via _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'])

Next Steps