Force hamming_left and hamming_right to be kwargs throughout API (#16)

* Force hamming_left and hamming_right to be kwargs throughout API * Don't change order of args in postselect_and_subsample * typo
Qiskit · Sep 13, 2024 · 147405a · 147405a
1 parent 10a7332
commit 147405a
Show file tree

Hide file tree

Showing 13 changed files with 130 additions and 74 deletions.
diff --git a/README.md b/README.md
@@ -35,7 +35,7 @@ This package contains the Qiskit addon for sample-based quantum diagonalization
 
 Classical distributed computing is used to process samples obtained from a quantum processor and to project and diagonalize a target Hamiltonian in a subspace spanned by them. This allows SQD to be robust to samples corrupted by quantum noise and deal with large Hamiltonians, such as chemistry Hamiltonians with millions of interaction terms, beyond the reach of any exact diagonalization methods. 
 
-The SQD tool can target Hamiltonians expressed as linear combination of Pauli operators, or second-quantized fermionic operators. The input samples are obtained by quantum circuits defined by the user, which are believed to be good representations of eigenstates (e.g. the ground state) of a target operator. The convergence rate of SQD as a function of the number of samples improves with the sparseness of the target eigenstate. 
+The SQD tool can target Hamiltonians expressed as linear combinations of Pauli operators, or second-quantized fermionic operators. The input samples are obtained by quantum circuits defined by the user, which are believed to be good representations of eigenstates (e.g. the ground state) of a target operator. The convergence rate of SQD as a function of the number of samples improves with the sparseness of the target eigenstate. 
 
 The projection and diagonalization steps are performed by a classical solver. We provide here two generic solvers, one for fermionic systems and another for qubit systems. Other solvers that might be more efficient for specific systems can be interfaced by the users.
 

diff --git a/docs/how_tos/choose_subspace_dimension.ipynb b/docs/how_tos/choose_subspace_dimension.ipynb
diff --git a/docs/how_tos/integrate_dice_solver.ipynb b/docs/how_tos/integrate_dice_solver.ipynb
@@ -83,18 +83,18 @@
     "            occupancies_bitwise,\n",
     "            num_elec_a,\n",
     "            num_elec_b,\n",
-    "            # rand_seed=rand_seed,\n",
+    "            rand_seed=rand_seed,\n",
     "        )\n",
     "\n",
     "    # Throw out samples with incorrect hamming weight and create batches of subsamples.\n",
     "    batches = postselect_and_subsample(\n",
     "        bs_mat_tmp,\n",
     "        probs_arr_tmp,\n",
-    "        num_elec_a,\n",
-    "        num_elec_b,\n",
-    "        samples_per_batch,\n",
-    "        n_batches,\n",
-    "        # rand_seed=rand_seed,\n",
+    "        hamming_right=num_elec_a,\n",
+    "        hamming_left=num_elec_b,\n",
+    "        samples_per_batch=samples_per_batch,\n",
+    "        num_batches=n_batches,\n",
+    "        rand_seed=rand_seed,\n",
     "    )\n",
     "    # Run eigenstate solvers in a loop. This loop should be parallelized for larger problems.\n",
     "    int_e = np.zeros(n_batches)\n",

diff --git a/docs/how_tos/select_open_closed_shell.ipynb b/docs/how_tos/select_open_closed_shell.ipynb
@@ -147,10 +147,10 @@
     "batches = postselect_and_subsample(\n",
     "    bitstring_matrix_full,\n",
     "    probs_arr_full,\n",
-    "    num_elec_a,\n",
-    "    num_elec_b,\n",
-    "    samples_per_batch,\n",
-    "    n_batches,\n",
+    "    hamming_right=num_elec_a,\n",
+    "    hamming_left=num_elec_b,\n",
+    "    samples_per_batch=samples_per_batch,\n",
+    "    num_batches=n_batches,\n",
     "    rand_seed=rand_seed,\n",
     ")\n",
     "\n",
@@ -406,10 +406,10 @@
     "batches = postselect_and_subsample(\n",
     "    bitstring_matrix_full,\n",
     "    probs_arr_full,\n",
-    "    num_elec_a,\n",
-    "    num_elec_b,\n",
-    "    samples_per_batch,\n",
-    "    n_batches,\n",
+    "    hamming_right=num_elec_a,\n",
+    "    hamming_left=num_elec_b,\n",
+    "    samples_per_batch=samples_per_batch,\n",
+    "    num_batches=n_batches,\n",
     "    rand_seed=rand_seed,\n",
     ")\n",
     "\n",

diff --git a/docs/how_tos/use_oo_to_optimize_hamiltonian_basis.ipynb b/docs/how_tos/use_oo_to_optimize_hamiltonian_basis.ipynb
@@ -163,10 +163,10 @@
     "    batches = postselect_and_subsample(\n",
     "        bs_mat_tmp,\n",
     "        probs_arr_tmp,\n",
-    "        num_elec_a,\n",
-    "        num_elec_b,\n",
-    "        samples_per_batch,\n",
-    "        n_batches,\n",
+    "        hamming_right=num_elec_a,\n",
+    "        hamming_left=num_elec_b,\n",
+    "        samples_per_batch=samples_per_batch,\n",
+    "        num_batches=n_batches,\n",
     "        rand_seed=rand_seed,\n",
     "    )\n",
     "\n",

diff --git a/docs/index.rst b/docs/index.rst
@@ -8,7 +8,7 @@ This package contains the Qiskit addon for sample-based quantum diagonalization
 
 Classical distributed computing is used to process samples obtained from a quantum processor, and to project and diagonalize a target Hamiltonian in a subspace spanned by them. This allows SQD to be robust to samples corrupted by quantum noise and deal with large Hamiltonians, such as chemistry Hamiltonians with millions of interaction terms, beyond the reach of any exact diagonalization methods.  
 
-The SQD tool can target Hamiltonians expressed as linear combination of Pauli operators, or second-quantized fermionic operators. The input samples are obtained by quantum circuits defined by the user, which are believed to be good representations of eigenstates (e.g. the ground state) of a target operator. The convergence rate of SQD as a function of the number of samples improves with the sparseness of the target eigenstate. 
+The SQD tool can target Hamiltonians expressed as linear combinations of Pauli operators, or second-quantized fermionic operators. The input samples are obtained by quantum circuits defined by the user, which are believed to be good representations of eigenstates (e.g. the ground state) of a target operator. The convergence rate of SQD as a function of the number of samples improves with the sparseness of the target eigenstate. 
 
 The projection and diagonalization steps are performed by a classical solver. We provide here two generic solvers, one for fermionic systems and another for qubit systems. Other solvers that might be more efficient for specific systems can be interfaced by the users.
 

diff --git a/docs/tutorials/01_chemistry_hamiltonian.ipynb b/docs/tutorials/01_chemistry_hamiltonian.ipynb
@@ -123,7 +123,7 @@
      "name": "stderr",
      "output_type": "stream",
      "text": [
-      "Overwritten attributes  get_hcore get_ovlp  of <class 'pyscf.scf.hf_symm.SymAdaptedRHF'>\n"
+      "Overwritten attributes  get_ovlp get_hcore  of <class 'pyscf.scf.hf_symm.SymAdaptedRHF'>\n"
      ]
     }
    ],
@@ -236,8 +236,8 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Gate counts (w/o pre-init passes): OrderedDict({'rz': 7403, 'sx': 6014, 'ecr': 2232, 'x': 315, 'measure': 32, 'barrier': 1})\n",
-      "Gate counts (w/ pre-init passes): OrderedDict({'rz': 4163, 'sx': 3189, 'ecr': 1262, 'x': 209, 'measure': 32, 'barrier': 1})\n"
+      "Gate counts (w/o pre-init passes): OrderedDict({'rz': 7402, 'sx': 6009, 'ecr': 2232, 'x': 317, 'measure': 32, 'barrier': 1})\n",
+      "Gate counts (w/ pre-init passes): OrderedDict({'rz': 4158, 'sx': 3186, 'ecr': 1262, 'x': 210, 'measure': 32, 'barrier': 1})\n"
      ]
     }
    ],
@@ -414,10 +414,10 @@
     "    batches = postselect_and_subsample(\n",
     "        bs_mat_tmp,\n",
     "        probs_arr_tmp,\n",
-    "        num_elec_a,\n",
-    "        num_elec_b,\n",
-    "        samples_per_batch,\n",
-    "        n_batches,\n",
+    "        hamming_right=num_elec_a,\n",
+    "        hamming_left=num_elec_b,\n",
+    "        samples_per_batch=samples_per_batch,\n",
+    "        num_batches=n_batches,\n",
     "        rand_seed=rand_seed,\n",
     "    )\n",
     "\n",

diff --git a/qiskit_addon_sqd/configuration_recovery.py b/qiskit_addon_sqd/configuration_recovery.py
@@ -30,7 +30,7 @@
 
 
 def post_select_by_hamming_weight(
-    bitstring_matrix: np.ndarray, hamming_right: int, hamming_left: int
+    bitstring_matrix: np.ndarray, *, hamming_right: int, hamming_left: int
 ) -> np.ndarray:
     """
     Post-select bitstrings based on the hamming weight of each half.
@@ -62,7 +62,6 @@ def recover_configurations(
     avg_occupancies: np.ndarray,
     num_elec_a: int,
     num_elec_b: int,
-    *,
     rand_seed: int | None = None,
 ) -> tuple[np.ndarray, np.ndarray]:
     """

diff --git a/qiskit_addon_sqd/counts.py b/qiskit_addon_sqd/counts.py
@@ -90,6 +90,7 @@ def generate_counts_uniform(
 def generate_counts_bipartite_hamming(
     num_samples: int,
     num_bits: int,
+    *,
     hamming_right: int,
     hamming_left: int,
     rand_seed: None | int = None,

diff --git a/qiskit_addon_sqd/subsampling.py b/qiskit_addon_sqd/subsampling.py
@@ -32,6 +32,7 @@
 def postselect_and_subsample(
     bitstring_matrix: np.ndarray,
     probabilities: np.ndarray,
+    *,
     hamming_right: int,
     hamming_left: int,
     samples_per_batch: int,
@@ -76,7 +77,9 @@ def postselect_and_subsample(
         raise ValueError("Hamming weight must be specified with a non-negative integer.")
 
     # Post-select only bitstrings with correct hamming weight
-    mask_postsel = post_select_by_hamming_weight(bitstring_matrix, hamming_left, hamming_right)
+    mask_postsel = post_select_by_hamming_weight(
+        bitstring_matrix, hamming_right=hamming_right, hamming_left=hamming_left
+    )
     bs_mat_postsel = bitstring_matrix[mask_postsel]
     probs_postsel = probabilities[mask_postsel]
     probs_postsel = np.abs(probs_postsel) / np.sum(np.abs(probs_postsel))

diff --git a/releasenotes/notes/hamming-kwarg-c73098a4c756453e.yaml b/releasenotes/notes/hamming-kwarg-c73098a4c756453e.yaml
@@ -0,0 +1,55 @@
+---
+upgrade:
+  - |
+    
+    The :func:`qiskit_addon_sqd.counts.generate_counts_bipartite_hamming`, :func:`qiskit_addon_sqd.subsampling.postselect_and_subsample`, and :func:`qiskit_addon_sqd.configuration_recovery.post_select_by_hamming_weight` now require the ``hamming_right`` and ``hamming_left`` arguments to be specified as keyword arguments. Additionally, the ``samples_per_batch`` and ``n_batches`` arguments to :func:`qiskit_addon_sqd.subsampling.post_select_by_hamming_weight` should now be passed as keyword arguments.
+
+    To upgrade
+
+    .. code-block:: python
+        
+        from qiskit_addon_sqd.configuration_recovery import post_select_by_hamming_weight
+        from qiskit_addon_sqd.subsampling import postselect_and_subsample
+        from qiskit_addon_sqd.counts import generate_counts_bipartite_hamming
+
+        counts = generate_counts_bipartite_hamming(num_samples, num_bits, num_elec_a, num_elec_b)
+
+        ...
+
+        bs_mat = post_select_by_hamming_weight(bs_mat_full, num_elec_a, num_elec_b)    
+
+        ...
+        
+        batches = postselect_and_subsample(
+            bs_mat,
+            probs_arr,
+            num_elec_a,
+            num_elec_b,
+            samples_per_batch,
+            n_batches,
+        )
+
+    should be changed to
+
+    .. code-block:: python
+        
+        from qiskit_addon_sqd.configuration_recovery import post_select_by_hamming_weight
+        from qiskit_addon_sqd.subsampling import postselect_and_subsample
+        from qiskit_addon_sqd.counts import generate_counts_bipartite_hamming
+
+        counts = generate_counts_bipartite_hamming(num_samples, num_bits, hamming_right=num_elec_a, hamming_left=num_elec_b)
+
+        ...
+
+        bs_mat = post_select_by_hamming_weight(bs_mat_full, hamming_right=num_elec_a, hamming_left=num_elec_b)
+
+        ...
+        
+        batches = postselect_and_subsample(
+            bs_mat,
+            probs_arr,
+            hamming_right=num_elec_a,
+            hamming_left=num_elec_b,
+            samples_per_batch=samples_per_batch,
+            n_batches=n_batches,
+        )
diff --git a/test/test_counts.py b/test/test_counts.py
@@ -76,7 +76,7 @@ def test_generate_counts_bipartite_hamming(self):
             hamming_left = 3
             hamming_right = 2
             counts = generate_counts_bipartite_hamming(
-                num_samples, num_bits, hamming_right, hamming_left
+                num_samples, num_bits, hamming_right=hamming_right, hamming_left=hamming_left
             )
             self.assertLessEqual(len(counts), num_samples)
             for bs in counts:
@@ -92,7 +92,7 @@ def test_generate_counts_bipartite_hamming(self):
             hamming_right = 2
             with pytest.raises(ValueError) as e_info:
                 generate_counts_bipartite_hamming(
-                    num_samples, num_bits, hamming_right, hamming_left
+                    num_samples, num_bits, hamming_right=hamming_right, hamming_left=hamming_left
                 )
             self.assertEqual(
                 "The number of bits must be specified with an even integer.", e_info.value.args[0]
@@ -104,7 +104,7 @@ def test_generate_counts_bipartite_hamming(self):
             hamming_right = 2
             with pytest.raises(ValueError) as e_info:
                 generate_counts_bipartite_hamming(
-                    num_samples, num_bits, hamming_right, hamming_left
+                    num_samples, num_bits, hamming_right=hamming_right, hamming_left=hamming_left
                 )
             self.assertEqual(
                 "The number of samples must be specified with a positive integer.",
@@ -117,7 +117,7 @@ def test_generate_counts_bipartite_hamming(self):
             hamming_right = 2
             with pytest.raises(ValueError) as e_info:
                 generate_counts_bipartite_hamming(
-                    num_samples, num_bits, hamming_right, hamming_left
+                    num_samples, num_bits, hamming_right=hamming_right, hamming_left=hamming_left
                 )
             self.assertEqual(
                 "The number of bits must be specified with a positive integer.",
@@ -130,7 +130,7 @@ def test_generate_counts_bipartite_hamming(self):
             hamming_right = -1
             with pytest.raises(ValueError) as e_info:
                 generate_counts_bipartite_hamming(
-                    num_samples, num_bits, hamming_right, hamming_left
+                    num_samples, num_bits, hamming_right=hamming_right, hamming_left=hamming_left
                 )
             self.assertEqual(
                 "Hamming weights must be specified as non-negative integers.", e_info.value.args[0]

diff --git a/test/test_subsampling.py b/test/test_subsampling.py
@@ -138,10 +138,10 @@ def test_postselect_and_subsample(self):
             batches = postselect_and_subsample(
                 self.bitstring_matrix,
                 self.uniform_probs,
-                hamming_right,
-                hamming_left,
-                samples_per_batch,
-                num_batches,
+                hamming_right=hamming_right,
+                hamming_left=hamming_left,
+                samples_per_batch=samples_per_batch,
+                num_batches=num_batches,
             )
             self.assertEqual(num_batches, len(batches))
             for batch in batches:
@@ -158,10 +158,10 @@ def test_postselect_and_subsample(self):
             batches = postselect_and_subsample(
                 self.bitstring_matrix,
                 self.uniform_probs,
-                hamming_right,
-                hamming_left,
-                samples_per_batch,
-                num_batches,
+                hamming_right=hamming_right,
+                hamming_left=hamming_left,
+                samples_per_batch=samples_per_batch,
+                num_batches=num_batches,
             )
             self.assertEqual(num_batches, len(batches))
             for batch in batches:
@@ -178,10 +178,10 @@ def test_postselect_and_subsample(self):
             batches = postselect_and_subsample(
                 self.bitstring_matrix[1:],
                 self.uniform_probs[1:],
-                hamming_right,
-                hamming_left,
-                samples_per_batch,
-                num_batches,
+                hamming_right=hamming_right,
+                hamming_left=hamming_left,
+                samples_per_batch=samples_per_batch,
+                num_batches=num_batches,
             )
             self.assertEqual(num_batches, len(batches))
             for batch in batches:
@@ -195,10 +195,10 @@ def test_postselect_and_subsample(self):
                 postselect_and_subsample(
                     self.bitstring_matrix,
                     self.uniform_probs,
-                    hamming_right,
-                    hamming_left,
-                    samples_per_batch,
-                    num_batches,
+                    hamming_right=hamming_right,
+                    hamming_left=hamming_left,
+                    samples_per_batch=samples_per_batch,
+                    num_batches=num_batches,
                 )
             assert (
                 e_info.value.args[0]
@@ -213,10 +213,10 @@ def test_postselect_and_subsample(self):
                 postselect_and_subsample(
                     self.bitstring_matrix,
                     self.uniform_probs,
-                    hamming_right,
-                    hamming_left,
-                    samples_per_batch,
-                    num_batches,
+                    hamming_right=hamming_right,
+                    hamming_left=hamming_left,
+                    samples_per_batch=samples_per_batch,
+                    num_batches=num_batches,
                 )
             assert (
                 e_info.value.args[0]
@@ -231,10 +231,10 @@ def test_postselect_and_subsample(self):
                 postselect_and_subsample(
                     self.bitstring_matrix,
                     self.uniform_probs,
-                    hamming_right,
-                    hamming_left,
-                    samples_per_batch,
-                    num_batches,
+                    hamming_right=hamming_right,
+                    hamming_left=hamming_left,
+                    samples_per_batch=samples_per_batch,
+                    num_batches=num_batches,
                 )
             assert (
                 e_info.value.args[0]
@@ -249,10 +249,10 @@ def test_postselect_and_subsample(self):
                 postselect_and_subsample(
                     self.bitstring_matrix,
                     np.array([]),
-                    hamming_right,
-                    hamming_left,
-                    samples_per_batch,
-                    num_batches,
+                    hamming_right=hamming_right,
+                    hamming_left=hamming_left,
+                    samples_per_batch=samples_per_batch,
+                    num_batches=num_batches,
                 )
             assert (
                 e_info.value.args[0]
@@ -266,10 +266,10 @@ def test_postselect_and_subsample(self):
             batches = postselect_and_subsample(
                 np.array([]),
                 np.array([]),
-                hamming_left,
-                hamming_right,
-                samples_per_batch,
-                num_batches,
+                hamming_right=hamming_right,
+                hamming_left=hamming_left,
+                samples_per_batch=samples_per_batch,
+                num_batches=num_batches,
             )
             self.assertEqual(num_batches, len(batches))
             self.assertEqual(0, batches[0].shape[0])