Merge branch 'main' into bd-restructure-execution-mode-pages

Author: abbycross

docs/api/qiskit-addon-sqd/0.8/_package.json

@@ -0,0 +1,4 @@
+{
+  "name": "qiskit-addon-sqd",
+  "version": "0.8.1"
+}

docs/api/qiskit-addon-sqd/0.8/_toc.json

@@ -0,0 +1,34 @@
+{
+  "title": "Sample-based quantum diagonalization (SQD)",
+  "children": [
+    {
+      "title": "API index",
+      "url": "/api/qiskit-addon-sqd/0.8"
+    },
+    {
+      "title": "qiskit_addon_sqd.configuration_recovery",
+      "url": "/api/qiskit-addon-sqd/0.8/configuration-recovery"
+    },
+    {
+      "title": "qiskit_addon_sqd.counts",
+      "url": "/api/qiskit-addon-sqd/0.8/counts"
+    },
+    {
+      "title": "qiskit_addon_sqd.fermion",
+      "url": "/api/qiskit-addon-sqd/0.8/fermion"
+    },
+    {
+      "title": "qiskit_addon_sqd.qubit",
+      "url": "/api/qiskit-addon-sqd/0.8/qubit"
+    },
+    {
+      "title": "qiskit_addon_sqd.subsampling",
+      "url": "/api/qiskit-addon-sqd/0.8/subsampling"
+    },
+    {
+      "title": "Release notes",
+      "url": "/api/qiskit-addon-sqd/release-notes"
+    }
+  ],
+  "collapsed": true
+}

docs/api/qiskit-addon-sqd/0.8/configuration-recovery.mdx

@@ -0,0 +1,77 @@
+---
+title: configuration_recovery (v0.8)
+description: API reference for qiskit_addon_sqd.configuration_recovery in qiskit-addon-sqd v0.8
+in_page_toc_min_heading_level: 2
+python_api_type: module
+python_api_name: qiskit_addon_sqd.configuration_recovery
+---
+
+<span id="module-qiskit_addon_sqd.configuration_recovery" />
+
+<span id="configuration-recovery-qiskit-addon-sqd-configuration-recovery" />
+
+# Configuration recovery
+
+`qiskit_addon_sqd.configuration_recovery`
+
+Functions for performing self-consistent configuration recovery.
+
+### post\_select\_by\_hamming\_weight
+
+<Function id="qiskit_addon_sqd.configuration_recovery.post_select_by_hamming_weight" github="https://github.com/Qiskit/qiskit-addon-sqd/tree/stable/0.8/qiskit_addon_sqd/configuration_recovery.py#L24-L48" signature="post_select_by_hamming_weight(bitstring_matrix, *, hamming_right, hamming_left)">
+  Post-select bitstrings based on the hamming weight of each half.
+
+  **Parameters**
+
+  *   **bitstring\_matrix** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – A 2D array of `bool` representations of bit values such that each row represents a single bitstring
+  *   **hamming\_right** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The target hamming weight of the right half of bitstrings
+  *   **hamming\_left** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The target hamming weight of the left half of bitstrings
+
+  **Returns**
+
+  A mask signifying which samples (rows) were selected from the input matrix.
+
+  **Return type**
+
+  [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")
+</Function>
+
+### recover\_configurations
+
+<Function id="qiskit_addon_sqd.configuration_recovery.recover_configurations" github="https://github.com/Qiskit/qiskit-addon-sqd/tree/stable/0.8/qiskit_addon_sqd/configuration_recovery.py#L51-L117" signature="recover_configurations(bitstring_matrix, probabilities, avg_occupancies, num_elec_a, num_elec_b, rand_seed=None)">
+  Refine bitstrings based on average orbital occupancy and a target hamming weight.
+
+  This function refines each bit in isolation in an attempt to transform the Hilbert space represented by the input `bitstring_matrix` into a space closer to that which supports the ground state.
+
+  <Admonition title="Note" type="note">
+    This function makes the assumption that bit `i` represents the spin-down orbital corresponding to the spin-up orbital in bit `i + N` where `N` is the number of spatial orbitals and `i < N`.
+  </Admonition>
+
+  <Admonition title="Note" type="note">
+    The output configurations may not necessarily have correct hamming weight, as each bit is flipped in isolation from the other bits in the bitstring.
+  </Admonition>
+
+  **Parameters**
+
+  *   **bitstring\_matrix** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – A 2D array of `bool` representations of bit values such that each row represents a single bitstring
+  *   **probabilities** ([*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.13)")*\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")*]*) – A 1D array specifying a probability distribution over the bitstrings
+  *   **avg\_occupancies** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")) – A 1D array containing the mean occupancy of each orbital. It is assumed that `avg_occupancies[i]` corresponds to the orbital represented by column `i` in `bitstring_matrix`.
+  *   **num\_elec\_a** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The number of spin-up electrons in the system.
+  *   **num\_elec\_b** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The number of spin-down electrons in the system.
+  *   **rand\_seed** ([*Generator*](https://numpy.org/doc/stable/reference/random/generator.html#numpy.random.Generator "(in NumPy v2.1)")  *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *| None*) – A seed for controlling randomness
+
+  **Returns**
+
+  A refined bitstring matrix and an updated probability array.
+
+  **Return type**
+
+  [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)"), [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")]
+
+  **References**
+
+  **\[1]: J. Robledo-Moreno, et al., [Chemistry Beyond Exact Solutions on a Quantum-Centric Supercomputer](https://arxiv.org/abs/2405.05068),**
+
+  arXiv:2405.05068 \[quant-ph].
+</Function>
+

docs/api/qiskit-addon-sqd/0.8/counts.mdx

@@ -0,0 +1,103 @@
+---
+title: counts (v0.8)
+description: API reference for qiskit_addon_sqd.counts in qiskit-addon-sqd v0.8
+in_page_toc_min_heading_level: 2
+python_api_type: module
+python_api_name: qiskit_addon_sqd.counts
+---
+
+<span id="module-qiskit_addon_sqd.counts" />
+
+<span id="counts-qiskit-addon-sqd-counts" />
+
+# Counts
+
+`qiskit_addon_sqd.counts`
+
+Functions for transforming counts dictionaries.
+
+### counts\_to\_arrays
+
+<Function id="qiskit_addon_sqd.counts.counts_to_arrays" github="https://github.com/Qiskit/qiskit-addon-sqd/tree/stable/0.8/qiskit_addon_sqd/counts.py#L21-L40" signature="counts_to_arrays(counts)">
+  Convert a counts dictionary into a bitstring matrix and a probability array.
+
+  **Parameters**
+
+  **counts** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.13)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")  *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The counts dictionary to convert
+
+  **Returns**
+
+  *   A 2D array representing the sampled bitstrings. Each row represents a bitstring, and each element is a `bool` representation of the bit’s value
+  *   A 1D array containing the probability with which each bitstring was sampled
+
+  **Return type**
+
+  [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)"), [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")]
+</Function>
+
+### generate\_counts\_uniform
+
+<Function id="qiskit_addon_sqd.counts.generate_counts_uniform" github="https://github.com/Qiskit/qiskit-addon-sqd/tree/stable/0.8/qiskit_addon_sqd/counts.py#L43-L77" signature="generate_counts_uniform(num_samples, num_bits, rand_seed=None)">
+  Generate a bitstring counts dictionary of samples drawn from the uniform distribution.
+
+  **Parameters**
+
+  *   **num\_samples** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The number of samples to draw
+  *   **num\_bits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The number of bits in the bitstrings
+  *   **rand\_seed** ([*Generator*](https://numpy.org/doc/stable/reference/random/generator.html#numpy.random.Generator "(in NumPy v2.1)")  *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *| None*) – A seed for controlling randomness
+
+  **Returns**
+
+  A dictionary mapping bitstrings of length `num_bits` to the number of times they were sampled.
+
+  **Raises**
+
+  [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – `num_samples` and `num_bits` must be positive integers.
+
+  **Return type**
+
+  [dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.13)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)"), [int](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")]
+</Function>
+
+### generate\_counts\_bipartite\_hamming
+
+<Function id="qiskit_addon_sqd.counts.generate_counts_bipartite_hamming" github="https://github.com/Qiskit/qiskit-addon-sqd/tree/stable/0.8/qiskit_addon_sqd/counts.py#L80-L135" signature="generate_counts_bipartite_hamming(num_samples, num_bits, *, hamming_right, hamming_left, rand_seed=None)">
+  Generate a bitstring counts dictionary with specified bipartite hamming weight.
+
+  **Parameters**
+
+  *   **num\_samples** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The number of samples to draw
+  *   **num\_bits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The number of bits in the bitstrings
+  *   **hamming\_right** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The hamming weight on the right half of each bitstring
+  *   **hamming\_left** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The hamming weight on the left half of each bitstring
+  *   **rand\_seed** ([*Generator*](https://numpy.org/doc/stable/reference/random/generator.html#numpy.random.Generator "(in NumPy v2.1)")  *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *| None*) – A seed for controlling randomness
+
+  **Returns**
+
+  A dictionary mapping bitstrings to the number of times they were sampled. Each half of each bitstring in the output dictionary will have a hamming weight as specified by the inputs.
+
+  **Raises**
+
+  *   [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – `num_bits` and `num_samples` must be positive integers.
+  *   [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – Hamming weights must be specified as non-negative integers.
+  *   [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – `num_bits` must be even.
+
+  **Return type**
+
+  [dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.13)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)"), [int](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")]
+</Function>
+
+### normalize\_counts\_dict
+
+<Function id="qiskit_addon_sqd.counts.normalize_counts_dict" github="https://github.com/Qiskit/qiskit-addon-sqd/tree/stable/0.8/qiskit_addon_sqd/counts.py#L138-L145" signature="normalize_counts_dict(counts)">
+  Convert a counts dictionary into a probability dictionary.
+
+  **Parameters**
+
+  **counts** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.13)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)")*,* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")  *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*)
+
+  **Return type**
+
+  [dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.13)")\[[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)"), [float](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")]
+</Function>
+