Force hamming_left and hamming_right to be kwargs throughout API

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",
+    "        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",

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",
     "    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",
     "    rand_seed=rand_seed,\n",
     ")\n",
     "\n",

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",
     "        rand_seed=rand_seed,\n",
     "    )\n",
     "\n",

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': 7421, 'sx': 6016, 'ecr': 2240, 'x': 324, 'measure': 32, 'barrier': 1})\n",
+      "Gate counts (w/ pre-init passes): OrderedDict({'rz': 4160, 'sx': 3189, 'ecr': 1262, 'x': 208, '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",
     "        rand_seed=rand_seed,\n",
     "    )\n",
     "\n",

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]:
     """

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,

qiskit_addon_sqd/subsampling.py

@@ -32,10 +32,11 @@
 def postselect_and_subsample(
     bitstring_matrix: np.ndarray,
     probabilities: np.ndarray,
-    hamming_right: int,
-    hamming_left: int,
     samples_per_batch: int,
     num_batches: int,
+    *,
+    hamming_right: int,
+    hamming_left: int,
     rand_seed: int | None = None,
 ) -> list[np.ndarray]:
     """
@@ -52,10 +53,10 @@ def postselect_and_subsample(
         bitstring_matrix: A 2D array of ``bool`` representations of bit
             values such that each row represents a single bitstring.
         probabilities: A 1D array specifying a probability distribution over the bitstrings
-        hamming_right: The target hamming weight for the right half of sampled bitstrings
-        hamming_left: The target hamming weight for the left half of sampled bitstrings
         samples_per_batch: The number of samples to draw for each batch
         num_batches: The number of batches to generate
+        hamming_right: The target hamming weight for the right half of sampled bitstrings
+        hamming_left: The target hamming weight for the left half of sampled bitstrings
         rand_seed: A seed to control random behavior
 
     Returns:
@@ -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))

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.
+
+    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,
+            samples_per_batch,
+            n_batches,
+            hamming_right=num_elec_a,
+            hamming_left=num_elec_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]

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,
             )
             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,
             )
             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,
             )
             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,
                 )
             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,
                 )
             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,
                 )
             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,
                 )
             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,
             )
             self.assertEqual(num_batches, len(batches))
             self.assertEqual(0, batches[0].shape[0])