Generate qiskit-addon-mpf 0.2 (#2365)

This release is notable because it changes the config in two ways:

* We now show release notes
* We add a TocGrouping

<img width="259" alt="Screenshot 2024-11-21 at 10 30 54 AM"
src="https://github.com/user-attachments/assets/d29b41b6-a5b4-482a-9229-bca9a5340191">

docs/api/qiskit-addon-mpf/0.1/_package.json

@@ -0,0 +1,4 @@
+{
+  "name": "qiskit-addon-mpf",
+  "version": "0.1.0"
+}

docs/api/qiskit-addon-mpf/0.1/_toc.json

@@ -0,0 +1,18 @@
+{
+  "title": "Multi-product formulas (MPF)",
+  "children": [
+    {
+      "title": "API index",
+      "url": "/api/qiskit-addon-mpf/0.1"
+    },
+    {
+      "title": "qiskit_addon_mpf.static",
+      "url": "/api/qiskit-addon-mpf/0.1/static"
+    },
+    {
+      "title": "Release notes",
+      "url": "/api/qiskit-addon-mpf/release-notes"
+    }
+  ],
+  "collapsed": true
+}

docs/api/qiskit-addon-mpf/0.1/index.mdx

@@ -0,0 +1,11 @@
+---
+title: Multi-product formulas (MPF) API documentation (v0.1)
+description: Index of all the modules in qiskit-addon-mpf v0.1.
+---
+
+<span id="qiskit-addon-mpf-api-reference" />
+
+# `qiskit-addon-mpf` API reference
+
+*   [Static MPFs (`qiskit_addon_mpf.static`)](static)
+

docs/api/qiskit-addon-mpf/0.1/static.mdx

@@ -0,0 +1,260 @@
+---
+title: static (v0.1)
+description: API reference for qiskit_addon_mpf.static in qiskit-addon-mpf v0.1
+in_page_toc_min_heading_level: 2
+python_api_type: module
+python_api_name: qiskit_addon_mpf.static
+---
+
+<span id="module-qiskit_addon_mpf.static" />
+
+<span id="static-mpfs-qiskit-addon-mpf-static" />
+
+# Static MPFs
+
+`qiskit_addon_mpf.static`
+
+Static MPFs.
+
+## Linear system of equations utilities
+
+### LSE
+
+<Class id="qiskit_addon_mpf.static.LSE" github="https://github.com/Qiskit/qiskit-addon-mpf/tree/stable/0.1/qiskit_addon_mpf/static/lse.py#L23-L60" signature="LSE(A, b)" modifiers="class">
+  A `namedtuple` representing a linear system of equations.
+
+$$
+A x = b
+$$
+
+  Create new instance of LSE(A, b)
+
+  **Parameters**
+
+  *   **A** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)"))
+  *   **b** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)"))
+
+  #### A
+
+  <Attribute id="qiskit_addon_mpf.static.LSE.A" attributeTypeHint="ndarray">
+    The left hand side of the LSE.
+  </Attribute>
+
+  #### b
+
+  <Attribute id="qiskit_addon_mpf.static.LSE.b" attributeTypeHint="ndarray">
+    The right hand side of the LSE.
+  </Attribute>
+
+  #### count
+
+  <Function id="qiskit_addon_mpf.static.LSE.count" signature="count(value, /)">
+    Return number of occurrences of value.
+  </Function>
+
+  #### index
+
+  <Function id="qiskit_addon_mpf.static.LSE.index" signature="index(value, start=0, stop=9223372036854775807, /)">
+    Return first index of value.
+
+    Raises ValueError if the value is not present.
+  </Function>
+
+  #### solve
+
+  <Function id="qiskit_addon_mpf.static.LSE.solve" github="https://github.com/Qiskit/qiskit-addon-mpf/tree/stable/0.1/qiskit_addon_mpf/static/lse.py#L41-L60" signature="solve()">
+    Return the solution to this LSE: $x=A^{-1}b$.
+
+    **Returns**
+
+    The solution to this LSE.
+
+    **Raises**
+
+    [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – if this LSE is parameterized with unassigned values.
+
+    **Return type**
+
+    [*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")
+  </Function>
+
+  #### x
+
+  <Attribute id="qiskit_addon_mpf.static.LSE.x" attributeTypeHint="Variable">
+    Returns the \$x\$ [`Variable`](https://www.cvxpy.org/api_reference/cvxpy.expressions.html#cvxpy.expressions.variable.Variable "(in CVXPY v1.5)").
+  </Attribute>
+</Class>
+
+### setup\_lse
+
+<Function id="qiskit_addon_mpf.static.setup_lse" github="https://github.com/Qiskit/qiskit-addon-mpf/tree/stable/0.1/qiskit_addon_mpf/static/lse.py#L63-L131" signature="setup_lse(trotter_steps, *, order=1, symmetric=False)">
+  Return the linear system of equations for computing the static MPF coefficients.
+
+  This function constructs the following linear system of equations:
+
+$$
+A x = b,
+$$
+
+  with
+
+$$
+\begin{split}A_{0,j} &= 1 \\
+A_{i>0,j} &= k_{j}^{-(\chi + s(i-1))} \\
+b_0 &= 1 \\
+b_{i>0} &= 0\end{split}
+$$
+
+  where \$\chi\$ is the `order`, \$s\$ is \$2\$ if `symmetric` is `True` and \$1\$ oterhwise, \$k\_\{j}\$ are the `trotter_steps`, and \$x\$ are the variables to solve for. The indices \$i\$ and \$j\$ start at \$0\$.
+
+  Here is an example:
+
+  ```python
+  >>> from qiskit_addon_mpf.static import setup_lse
+  >>> lse = setup_lse([1,2,3], order=2, symmetric=True)
+  >>> print(lse.A)
+  [[1.         1.         1.        ]
+   [1.         0.25       0.11111111]
+   [1.         0.0625     0.01234568]]
+  >>> print(lse.b)
+  [1. 0. 0.]
+  ```
+
+  **Parameters**
+
+  *   **trotter\_steps** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*] |* [*Parameter*](https://www.cvxpy.org/api_reference/cvxpy.expressions.html#cvxpy.expressions.constants.parameter.Parameter "(in CVXPY v1.5)")) – the sequence of trotter steps from which to build \$A\$. Rather than a list of integers, this may also be a [`Parameter`](https://www.cvxpy.org/api_reference/cvxpy.expressions.html#cvxpy.expressions.constants.parameter.Parameter "(in CVXPY v1.5)") instance of the desired size. In this case, the constructed [`LSE`](#qiskit_addon_mpf.static.LSE "qiskit_addon_mpf.static.LSE") is parameterized whose values must be assigned before it can be solved.
+  *   **order** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – the order of the individual product formulas making up the MPF.
+  *   **symmetric** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – whether the individual product formulas making up the MPF are symmetric. For example, the Lie-Trotter formula is not symmetric, while Suzuki-Trotter is.
+
+  **Returns**
+
+  An [`LSE`](#qiskit_addon_mpf.static.LSE "qiskit_addon_mpf.static.LSE").
+
+  **Return type**
+
+  [*LSE*](#qiskit_addon_mpf.static.LSE "qiskit_addon_mpf.static.lse.LSE")
+</Function>
+
+## Exact static MPF coefficients
+
+### setup\_exact\_model
+
+<Function id="qiskit_addon_mpf.static.setup_exact_model" github="https://github.com/Qiskit/qiskit-addon-mpf/tree/stable/0.1/qiskit_addon_mpf/static/exact.py#L22-L73" signature="setup_exact_model(lse)">
+  Construct a [`cvxpy.Problem`](https://www.cvxpy.org/api_reference/cvxpy.problems.html#cvxpy.Problem "(in CVXPY v1.5)") for finding exact static MPF coefficients.
+
+  <Admonition title="Note" type="note">
+    The coefficients found via this optimization problem will be identical to the analytical ones obtained from the [`LSE.solve()`](#qiskit_addon_mpf.static.LSE.solve "qiskit_addon_mpf.static.LSE.solve") method. This additional interface exists to highlight the parallel to the [`setup_approximate_model()`](#qiskit_addon_mpf.static.setup_approximate_model "qiskit_addon_mpf.static.setup_approximate_model") interface. It also serves educational purposes for how-to approach optimization problems targeting MPF coefficients.
+  </Admonition>
+
+  The optimization problem constructed by this class is defined as follows:
+
+  *   the cost function minimizes the L1-norm ([`norm1`](https://www.cvxpy.org/api_reference/cvxpy.atoms.other_atoms.html#cvxpy.atoms.norm1.norm1 "(in CVXPY v1.5)")) of the variables ([`LSE.x`](#qiskit_addon_mpf.static.LSE.x "qiskit_addon_mpf.static.LSE.x"))
+
+  *   the constraints correspond to each equation of the [`LSE`](#qiskit_addon_mpf.static.LSE "qiskit_addon_mpf.static.LSE"):
+
+$$
+\sum_j A_{ij} x_j = b_i
+$$
+
+  Here is an example:
+
+  ```python
+  >>> from qiskit_addon_mpf.static import setup_lse, setup_exact_model
+  >>> lse = setup_lse([1,2,3], order=2, symmetric=True)
+  >>> problem, coeffs = setup_exact_model(lse)
+  >>> print(problem)
+  minimize norm1(x)
+  subject to Sum([1. 1. 1.] @ x, None, False) == 1.0
+             Sum([1. 0.25   0.11111111] @ x, None, False) == 0.0
+             Sum([1. 0.0625 0.01234568] @ x, None, False) == 0.0
+  ```
+
+  You can then solve the problem and extract the expansion coefficients like so:
+
+  ```python
+  >>> final_cost = problem.solve()
+  >>> print(coeffs.value)  
+  [ 0.04166667 -1.06666667  2.025     ]
+  ```
+
+  **Parameters**
+
+  **lse** ([*LSE*](#qiskit_addon_mpf.static.LSE "qiskit_addon_mpf.static.lse.LSE")) – the linear system of equations from which to build the model.
+
+  **Returns**
+
+  The optimization problem and coefficients variable.
+
+  **Return type**
+
+  [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[*Problem*](https://www.cvxpy.org/api_reference/cvxpy.problems.html#cvxpy.Problem "(in CVXPY v1.5)"), [*Variable*](https://www.cvxpy.org/api_reference/cvxpy.expressions.html#cvxpy.expressions.variable.Variable "(in CVXPY v1.5)")]
+
+  **References**
+
+  **\[1]: A. Carrera Vazquez et al., Quantum 7, 1067 (2023).**
+
+  [https://quantum-journal.org/papers/q-2023-07-25-1067/](https://quantum-journal.org/papers/q-2023-07-25-1067/)
+</Function>
+
+## Approximate static MPF coefficients
+
+### setup\_approximate\_model
+
+<Function id="qiskit_addon_mpf.static.setup_approximate_model" github="https://github.com/Qiskit/qiskit-addon-mpf/tree/stable/0.1/qiskit_addon_mpf/static/approximate.py#L22-L76" signature="setup_approximate_model(lse, *, max_l1_norm=10.0)">
+  Construct a [`cvxpy.Problem`](https://www.cvxpy.org/api_reference/cvxpy.problems.html#cvxpy.Problem "(in CVXPY v1.5)") for finding approximate static MPF coefficients.
+
+  The optimization problem constructed by this class is defined as follows:
+
+  *   the cost function minimizes the sum of squares ([`sum_squares()`](https://www.cvxpy.org/api_reference/cvxpy.atoms.other_atoms.html#cvxpy.atoms.sum_squares.sum_squares "(in CVXPY v1.5)")) of the distances to an exact solution for all equations of the [`LSE`](#qiskit_addon_mpf.static.LSE "qiskit_addon_mpf.static.LSE"):
+
+$$
+\sum_i \left( \sum_j A_{ij} x_j - b_i \right)^2
+$$
+
+  *   two constraints are set:
+
+      1.  the variables must sum to 1: $\sum_i x_i == 1$
+      2.  the L1-norm ([`norm1`](https://www.cvxpy.org/api_reference/cvxpy.atoms.other_atoms.html#cvxpy.atoms.norm1.norm1 "(in CVXPY v1.5)")) of the variables is bounded by `max_l1_norm`
+
+  Here is an example:
+
+  ```python
+  >>> from qiskit_addon_mpf.static import setup_lse, setup_approximate_model
+  >>> lse = setup_lse([1,2,3], order=2, symmetric=True)
+  >>> problem, coeffs = setup_approximate_model(lse, max_l1_norm=3.0)
+  >>> print(problem)
+  minimize quad_over_lin(Vstack([1. 1.     1.]         @ x + -1.0,
+                                [1. 0.25   0.11111111] @ x + -0.0,
+                                [1. 0.0625 0.01234568] @ x + -0.0), 1.0)
+  subject to Sum(x, None, False) == 1.0
+             norm1(x) <= 3.0
+  ```
+
+  You can then solve the problem and extract the expansion coefficients like so:
+
+  ```python
+  >>> final_cost = problem.solve()
+  >>> print(coeffs.value)  
+  [ 0.03513467 -1.          1.96486533]
+  ```
+
+  **Parameters**
+
+  *   **lse** ([*LSE*](#qiskit_addon_mpf.static.LSE "qiskit_addon_mpf.static.lse.LSE")) – the linear system of equations from which to build the model.
+  *   **max\_l1\_norm** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")) – the upper limit to use for the constrain of the L1-norm of the variables.
+
+  **Returns**
+
+  The optimization problem and coefficients variable.
+
+  **Return type**
+
+  [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[*Problem*](https://www.cvxpy.org/api_reference/cvxpy.problems.html#cvxpy.Problem "(in CVXPY v1.5)"), [*Variable*](https://www.cvxpy.org/api_reference/cvxpy.expressions.html#cvxpy.expressions.variable.Variable "(in CVXPY v1.5)")]
+
+  **References**
+
+  **\[1]: S. Zhuk et al., arXiv:2306.12569 (2023).**
+
+  [https://arxiv.org/abs/2306.12569](https://arxiv.org/abs/2306.12569)
+</Function>
+

docs/api/qiskit-addon-mpf/_package.json

@@ -1,4 +1,4 @@
 {
   "name": "qiskit-addon-mpf",
-  "version": "0.1.0"
+  "version": "0.2.0"
 }