261 lines
11 KiB
Plaintext
261 lines
11 KiB
Plaintext
---
|
||
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>
|
||
|