Remove some confusing mentions of base-10 integers in docs (#58)

* Remove some confusing mentions of base-10 integers in docs * qubit module * Update releasenotes/notes/deprecate-addr-526f0c5bf681f739.yaml Co-authored-by: Kevin J. Sung <[email protected]> * Remove all base10 mentions --------- Co-authored-by: Kevin J. Sung <[email protected]>
Qiskit · Sep 23, 2024 · 41febb6 · 41febb6
1 parent 0819a31
commit 41febb6
Show file tree

Hide file tree

Showing 4 changed files with 24 additions and 23 deletions.
diff --git a/docs/how_tos/project_pauli_operators_onto_hilbert_subspaces.ipynb b/docs/how_tos/project_pauli_operators_onto_hilbert_subspaces.ipynb
@@ -44,7 +44,8 @@
     "\n",
     "For this example we just generate length-22 random bitstrings. For the projection\n",
     "functions to work as expected, it is essential that the bitstrings that define\n",
-    "the subspace are unique and sorted according to their base-10 representation.\n",
+    "the subspace are unique and sorted in ascending order according to their unsigned\n",
+    "integer representation.\n",
     "\n",
     "This can be achieved with the ``qiskit_addon_sqd.qubit.sort_and_remove_duplicates()``\n",
     "function."

diff --git a/qiskit_addon_sqd/fermion.py b/qiskit_addon_sqd/fermion.py
@@ -312,7 +312,7 @@ def bitstring_matrix_to_sorted_addresses(
     bitstring_matrix: np.ndarray, open_shell: bool = False
 ) -> tuple[np.ndarray, np.ndarray]:
     """
-    Convert a bitstring matrix into a sorted array of unique, unsigned base-10 representations.
+    Convert a bitstring matrix into a sorted array of unique, unsigned integers.
 
     This function separates each bitstring in ``bitstring_matrix`` in half, flips the
     bits and translates them into integer representations, and finally appends them to
@@ -329,8 +329,8 @@ def bitstring_matrix_to_sorted_addresses(
             and right bitstrings.
 
     Returns:
-        A length-2 tuple of sorted, unique base-10 determinant addresses representing the
-        left (spin-down) and right (spin-up) halves of the bitstrings, respectively.
+        A length-2 tuple of sorted, unique determinants representing the left (spin-down) and
+        right (spin-up) halves of the bitstrings, respectively.
     """
     num_orbitals = bitstring_matrix.shape[1] // 2
     num_configs = bitstring_matrix.shape[0]

diff --git a/qiskit_addon_sqd/qubit.py b/qiskit_addon_sqd/qubit.py
@@ -73,7 +73,7 @@ def solve_qubit(
     if bitstring_matrix.shape[1] > 63:
         raise ValueError("Bitstrings (rows) in bitstring_matrix must have length < 64.")
 
-    # Projection requires the bitstring matrix be sorted in accordance with its base-10 representation
+    # Projection requires the bitstring matrix be sorted in ascending order by their unsigned integer representation
     bitstring_matrix = sort_and_remove_duplicates(bitstring_matrix)
 
     # Get a sparse representation of the projected operator
@@ -156,9 +156,9 @@ def sort_and_remove_duplicates(bitstring_matrix: np.ndarray, inplace: bool = Tru
     if not inplace:
         bitstring_matrix = bitstring_matrix.copy()
 
-    base_10 = _base_10_conversion_from_bts_matrix_vmap(bitstring_matrix)
+    bsmat_asints = _int_conversion_from_bts_matrix_vmap(bitstring_matrix)
 
-    _, indices = np.unique(base_10, return_index=True)
+    _, indices = np.unique(bsmat_asints, return_index=True)
 
     return bitstring_matrix[indices, :]
 
@@ -170,8 +170,8 @@ def matrix_elements_from_pauli(
     Find the matrix elements of a Pauli operator in the subspace defined by the bitstrings.
 
     .. note::
-       The bitstrings in the ``bitstring_matrix`` must be sorted and unique according
-       to their base-10 CI string representation. Otherwise the projection will return wrong
+       The bitstrings in the ``bitstring_matrix`` must be unique and sorted in ascending order
+       according to their unsigned integer representation. Otherwise the projection will return wrong
        results. This function does not explicitly check for uniqueness and order because
        this can be rather time consuming. See :func:`qiskit_addon_sqd.qubit.sort_and_remove_duplicates`
        for a simple way to ensure your bitstring matrix is well-formatted.
@@ -185,7 +185,7 @@ def matrix_elements_from_pauli(
         bitstring_matrix: A 2D array of ``bool`` representations of bit
             values such that each row represents a single bitstring.
             The bitstrings in the matrix must be sorted according to
-            their base-10 representation. Otherwise the projection will return
+            their unsigned integer representations. Otherwise the projection will return
             wrong results.
         pauli: A Pauli operator.
 
@@ -205,21 +205,21 @@ def matrix_elements_from_pauli(
 
     diag, sign, imag = _pauli_to_bool(pauli.to_label()[::-1])
 
-    base_10_array_rows = _base_10_conversion_from_bts_matrix_vmap(bitstring_matrix)
+    int_array_rows = _int_conversion_from_bts_matrix_vmap(bitstring_matrix)
 
     bs_mat_conn, matrix_elements = _connected_elements_and_amplitudes_bool_vmap(
         bitstring_matrix, diag, sign, imag
     )
 
-    base_10_array_cols = _base_10_conversion_from_bts_matrix_vmap(bs_mat_conn)
+    int_array_cols = _int_conversion_from_bts_matrix_vmap(bs_mat_conn)
 
-    indices = np.isin(base_10_array_cols, base_10_array_rows, assume_unique=True, kind="sort")
+    indices = np.isin(int_array_cols, int_array_rows, assume_unique=True, kind="sort")
 
     matrix_elements = matrix_elements[indices]
     row_array = row_array[indices]
-    base_10_array_cols = base_10_array_cols[indices]
+    int_array_cols = int_array_cols[indices]
 
-    col_array = np.searchsorted(base_10_array_rows, base_10_array_cols)
+    col_array = np.searchsorted(int_array_rows, int_array_cols)
 
     return matrix_elements, row_array, col_array
 
@@ -301,24 +301,24 @@ def _connected_elements_and_amplitudes_bool(
 )
 
 
-def _base_10_conversion_from_bts_array(bit_array: np.ndarray) -> Any:
+def _int_conversion_from_bts_array(bit_array: np.ndarray) -> Any:
     """
-    Convert a bit array to a base-10 representation.
+    Convert a bit array to an integer representation.
 
     NOTE: This can only handle up to 63 qubits. Then the integer will overflow
 
     Args:
         bit_array: A 1D array of ``bool`` representations of bit values.
 
     Returns:
-        Base-10 representation of the bit array.
+        Integer representation of the bit array.
     """
     n_qubits = len(bit_array)
-    base_10_array = 0.0
+    bitarray_asint = 0.0
     for i in range(n_qubits):
-        base_10_array = base_10_array + bit_array[i] * 2 ** (n_qubits - 1 - i)
+        bitarray_asint = bitarray_asint + bit_array[i] * 2 ** (n_qubits - 1 - i)
 
-    return base_10_array.astype("longlong")  # type: ignore
+    return bitarray_asint.astype("longlong")  # type: ignore
 
 
-_base_10_conversion_from_bts_matrix_vmap = jit(vmap(_base_10_conversion_from_bts_array, 0, 0))
+_int_conversion_from_bts_matrix_vmap = jit(vmap(_int_conversion_from_bts_array, 0, 0))
diff --git a/releasenotes/notes/deprecate-addr-526f0c5bf681f739.yaml b/releasenotes/notes/deprecate-addr-526f0c5bf681f739.yaml
@@ -1,7 +1,7 @@
 ---
 deprecations:
   - |
-    The ``addressess`` argument to :func:`qiskit_addon_sqd.fermion.solve_fermion` and :func:`qiskit_addon_sqd.fermion.optimize_orbitals` has been deprecated in favor of ``bitstring_matrix``. Users are no longer required to convert their configurations to base-10 determinants; instead, they should now pass in the bitstring matrix specifying the subspace onto which to project and diagonalize the Hamiltonian. The conversion to determinant addresses will be done internally.
+    The ``addresses`` argument to :func:`qiskit_addon_sqd.fermion.solve_fermion` and :func:`qiskit_addon_sqd.fermion.optimize_orbitals` has been deprecated in favor of ``bitstring_matrix``. Users are no longer required to convert their configurations to integers; instead, they should now pass in the bitstring matrix specifying the subspace onto which to project and diagonalize the Hamiltonian. The conversion to the integer representation of determinants will be done internally.
 upgrade:
   - |
     Specifying ``addresses`` as a keyword argument to :func:`qiskit_addon_sqd.fermion.solve_fermion` and :func:`qiskit_addon_sqd.fermion.optimize_orbitals` is no longer supported. Users may still pass ``addresses`` as the first positional argument; however, this usage is deprecated. Users are encouraged to pass the bitstring matrix defining the subspace as the first positional arguments to these functions, as shown below.