nlqk.embeddings.states

states.py

Quantum state functions and tools.

View Source

 1# coding: utf-8
 2
 3"""
 4states.py
 5
 6(C) 2025 by [Damir Cavar](http://damir.cavar.me/), James Bryan Graves, and [NLP Lab](https://nlp-lab.org/)
 7
 8Module: nlqk.embeddings.states
 9
10Quantum state functions and tools.
11"""
12
13
14import os
15if os.getenv("GITHUB_ACTIONS") == "true":
16    import numpy as np
17    from scipy.linalg import expm
18else:
19    try: # prefer RAPIDS libraries and GPU over numpy and CPU
20        import cupy as np  # Try to import cupy and alias it as np
21        from cupyx.scipy.linalg import expm
22        _USE_GPU = True
23    except ModuleNotFoundError:
24        import numpy as np  # If cupy not found, import numpy and alias it as np
25        from scipy.linalg import expm
26        _USE_GPU = False
27# from typing import Union, Sequence
28
29
30def hamiltonian_to_state(H: np.ndarray) -> np.ndarray:
31    """
32    Reconstructs a quantum state |ψ⟩ = e^{iH} |0⟩ from the given Hamiltonian H.
33
34    Args:
35        H np.ndarray: 
36            Hamiltonian matrix (must be square with dimension 2^n for some integer n).
37
38    Returns:
39        np.ndarray: Complex quantum state vector |ψ⟩ obtained by applying e^{iH} to |0⟩.
40
41    Raises:
42        ValueError: If H is not a square matrix or dimension is not a power of 2.
43    """
44    n_qubits = int(np.log2(H.shape[0]))
45    dim = 2 ** n_qubits
46
47    zero_state = np.zeros(dim, dtype=complex)
48    zero_state[0] = 1.0
49
50    U = expm(1j * H)
51
52    psi = U @ zero_state
53
54    return psi
55
56
57def check_states_equal(psi1: np.ndarray, psi2: np.ndarray, tol: float = 1e-6) -> bool:
58    """
59    Checks if two quantum states are equal up to a global phase factor.
60
61    Args:
62        psi1 np.ndarray: First quantum state vector.
63        psi2 np.ndarray: Second quantum state vector.
64        tol (float): Tolerance for the comparison. Defaults to 1e-6.
65
66    Returns:
67        bool: True if the states are equal up to global phase, False otherwise.
68
69    Note:
70        Two quantum states |ψ₁⟩ and |ψ₂⟩ are considered equal if |⟨ψ₁|ψ₂⟩| = 1,
71        meaning they differ only by a global phase factor e^{iθ}.
72    """
73    psi1 = psi1 / np.linalg.norm(psi1)
74    psi2 = psi2 / np.linalg.norm(psi2)
75    inner_product = np.abs(np.vdot(psi1, psi2))
76    return np.isclose(inner_product, 1.0, atol=tol)

def hamiltonian_to_state(H: cupy.ndarray) -> cupy.ndarray: View Source

31def hamiltonian_to_state(H: np.ndarray) -> np.ndarray:
32    """
33    Reconstructs a quantum state |ψ⟩ = e^{iH} |0⟩ from the given Hamiltonian H.
34
35    Args:
36        H np.ndarray: 
37            Hamiltonian matrix (must be square with dimension 2^n for some integer n).
38
39    Returns:
40        np.ndarray: Complex quantum state vector |ψ⟩ obtained by applying e^{iH} to |0⟩.
41
42    Raises:
43        ValueError: If H is not a square matrix or dimension is not a power of 2.
44    """
45    n_qubits = int(np.log2(H.shape[0]))
46    dim = 2 ** n_qubits
47
48    zero_state = np.zeros(dim, dtype=complex)
49    zero_state[0] = 1.0
50
51    U = expm(1j * H)
52
53    psi = U @ zero_state
54
55    return psi

Reconstructs a quantum state |ψ⟩ = e^{iH} |0⟩ from the given Hamiltonian H.

Args: H np.ndarray: Hamiltonian matrix (must be square with dimension 2^n for some integer n).

Returns: np.ndarray: Complex quantum state vector |ψ⟩ obtained by applying e^{iH} to |0⟩.

Raises: ValueError: If H is not a square matrix or dimension is not a power of 2.

def check_states_equal(psi1: cupy.ndarray, psi2: cupy.ndarray, tol: float = 1e-06) -> bool: View Source

58def check_states_equal(psi1: np.ndarray, psi2: np.ndarray, tol: float = 1e-6) -> bool:
59    """
60    Checks if two quantum states are equal up to a global phase factor.
61
62    Args:
63        psi1 np.ndarray: First quantum state vector.
64        psi2 np.ndarray: Second quantum state vector.
65        tol (float): Tolerance for the comparison. Defaults to 1e-6.
66
67    Returns:
68        bool: True if the states are equal up to global phase, False otherwise.
69
70    Note:
71        Two quantum states |ψ₁⟩ and |ψ₂⟩ are considered equal if |⟨ψ₁|ψ₂⟩| = 1,
72        meaning they differ only by a global phase factor e^{iθ}.
73    """
74    psi1 = psi1 / np.linalg.norm(psi1)
75    psi2 = psi2 / np.linalg.norm(psi2)
76    inner_product = np.abs(np.vdot(psi1, psi2))
77    return np.isclose(inner_product, 1.0, atol=tol)

Checks if two quantum states are equal up to a global phase factor.

Args: psi1 np.ndarray: First quantum state vector. psi2 np.ndarray: Second quantum state vector. tol (float): Tolerance for the comparison. Defaults to 1e-6.

Returns: bool: True if the states are equal up to global phase, False otherwise.

Note: Two quantum states |ψ₁⟩ and |ψ₂⟩ are considered equal if |⟨ψ₁|ψ₂⟩| = 1, meaning they differ only by a global phase factor e^{iθ}.