nlqk.embeddings.vectors

  1# coding: utf-8
  2
  3"""
  4vectors.py
  5
  6Module: nlqk.embeddings.vectors
  7
  8(C) 2025 by [Damir Cavar](http://damir.cavar.me/), James Bryan Graves, and [NLP Lab](https://nlp-lab.org/)
  9
 10Vector functionalities:
 11
 12"""
 13
 14
 15# from typing import Union, Sequence
 16import os
 17if os.getenv("GITHUB_ACTIONS") == "true":
 18    import numpy as np
 19else:
 20    try: # prefer RAPIDS libraries and GPU over numpy and CPU
 21        import cupy as np  # Try to import cupy and alias it as np
 22        _USE_GPU = True
 23    except ModuleNotFoundError:
 24        import numpy as np  # If cupy not found, import numpy and alias it as np
 25        _USE_GPU = False
 26# import GPUtil  # If you're using GPUtil
 27
 28
 29# Example Usage:
 30
 31
 32def cosine_similarity(vec1: np.ndarray, vec2: np.ndarray, tol: float = 1e-12) -> complex:
 33    """
 34    Computes the cosine similarity between two vectors.
 35
 36    Args:
 37        vec1 np.ndarray: First input vector.
 38        vec2 np.ndarray: Second input vector.
 39        tol (float): Threshold below which vector norm is treated as zero. Defaults to 1e-12.
 40
 41    Returns:
 42        float: Cosine similarity value. For real inputs: value in [-1, 1].
 43
 44    Raises:
 45        ZeroDivisionError: If either vector has zero length (norm below tolerance).
 46    """
 47    #if not np.iscomplexobj(vec1):
 48    #    vec1 = vec1.astype(complex)
 49    #if not np.iscomplexobj(vec2):
 50    #    vec2 = vec2.astype(complex) # np.ravel(np.asarray(vec2))
 51    # if vectors are normalized cosine similarity is equivalent to the dot product
 52    if is_normalized(vec1) and is_normalized(vec2):
 53        return np.dot(vec1, vec2)
 54
 55    n1, n2 = np.linalg.norm(vec1), np.linalg.norm(vec2)
 56    if n1 < tol or n2 < tol:
 57        raise ZeroDivisionError("Zero-length vector")
 58
 59    return complex(np.vdot(vec1, vec2) / (n1 * n2))
 60
 61
 62def is_normalized(vector: np.ndarray, tolerance: float=1e-9) -> bool:
 63    """
 64    Checks if a NumPy vector is normalized (its L2 norm is approximately 1).
 65
 66    Args:
 67        vector (Union[Sequence[Union[int, float, complex]], np.ndarray]): The input vector.
 68        tolerance (float): The allowed tolerance for comparison with 1.
 69
 70    Returns:
 71        bool: True if the vector is normalized, False otherwise.
 72    """
 73    if np.isclose(np.linalg.norm(vector), 1.0, atol=tolerance):
 74        return True
 75    return False
 76
 77
 78def normalize(vector: np.ndarray) -> np.ndarray:
 79    """
 80    Normalizes a vector to unit length.
 81
 82    Args:
 83        vector np.ndarray: Input vector to normalize.
 84
 85    Returns:
 86        np.ndarray: The normalized vector with unit norm.
 87
 88    Raises:
 89        ValueError: If the input vector has zero norm and cannot be normalized.
 90    """
 91    norm = np.linalg.norm(vector)
 92    if norm != 0:
 93        return vector / norm
 94    raise ValueError("Zero vector cannot be normalized.")
 95
 96
 97
 98def pad_vector(vector: np.ndarray, target_size: int) -> np.ndarray:
 99    """
100    Pads a vector with zeros to reach the specified target size.
101
102    Args:
103        vector np.ndarray: Input vector to pad.
104        target_size (int): The desired size of the output vector.
105
106    Returns:
107        np.ndarray: Padded vector of length target_size with complex dtype.
108
109    Raises:
110        ValueError: If the input vector is larger than the target size.
111    """
112    return np.pad(vector, (0, target_size - len(vector)), mode='constant')
113
114
115def pair_real_to_complex(vector: np.ndarray) -> np.ndarray:
116    """
117    Converts a real-valued vector into a complex-valued vector by pairing adjacent elements.
118
119    Args:
120        vector np.ndarray: Real-valued input vector, if not even length it will be padded to even length.
121
122    Returns:
123        np.ndarray: Complex-valued vector where each complex number is formed from consecutive pairs.
124
125    Raises:
126        ValueError: If the vector length is odd and cannot be paired into complex numbers.
127    """
128    if len(vector) > 0:
129        if len(vector) % 2 != 0:
130            # automatically pad with a 0
131            vector = pad_vector(vector, len(vector) + 1)
132    else:
133        raise ValueError("Vector length must be even to pair into complex numbers.")
134    return np.array([vector[i] + 1j * vector[i+1] for i in range(0, len(vector), 2)])
135
136
137
138def pad_vectors(vectors: np.ndarray, size: int) -> np.ndarray:
139    """Pad rows with zeros to size.
140
141    Args:
142        vectors np.ndarray: matrix of vectors to be padded, all the same length.
143        size int: target length of vectors.
144
145    Returns:
146        np.ndarray: Padded vectors.
147    """
148    return np.pad(vectors, [(0, 0), (0, size - vectors.shape[1])], mode='constant')