284 lines
12 KiB
Plaintext
284 lines
12 KiB
Plaintext
---
|
||
title: costs (latest version)
|
||
description: API reference for qiskit_addon_mpf.costs in the latest version of qiskit-addon-mpf
|
||
in_page_toc_min_heading_level: 2
|
||
python_api_type: module
|
||
python_api_name: qiskit_addon_mpf.costs
|
||
---
|
||
|
||
<span id="module-qiskit_addon_mpf.costs" />
|
||
|
||
<span id="cost-functions-qiskit-addon-mpf-costs" />
|
||
|
||
# Cost Functions
|
||
|
||
`qiskit_addon_mpf.costs`
|
||
|
||
Cost functions for MPF coefficients.
|
||
|
||
This module provides a number of optimization problem generator functions, each implementing a different cost function as the problem’s target objective. All of the functions provided by this module take a linear system of equations ([`LSE`](#qiskit_addon_mpf.costs.LSE "qiskit_addon_mpf.costs.LSE")) encoding the parameters of the optimization problem as their first argument.
|
||
|
||
### LSE
|
||
|
||
<Class id="qiskit_addon_mpf.costs.LSE" github="https://github.com/Qiskit/qiskit-addon-mpf/tree/stable/0.3/qiskit_addon_mpf/costs/lse.py#L23-L73" signature="LSE(A, b)" modifiers="class">
|
||
Bases: [`NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple "(in Python v3.13)")
|
||
|
||
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.2)"))
|
||
* **b** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.2)"))
|
||
|
||
#### A
|
||
|
||
<Attribute id="qiskit_addon_mpf.costs.LSE.A" attributeTypeHint="ndarray">
|
||
The left hand side of the LSE.
|
||
</Attribute>
|
||
|
||
#### b
|
||
|
||
<Attribute id="qiskit_addon_mpf.costs.LSE.b" attributeTypeHint="ndarray">
|
||
The right hand side of the LSE.
|
||
</Attribute>
|
||
|
||
#### count
|
||
|
||
<Function id="qiskit_addon_mpf.costs.LSE.count" signature="count(value, /)">
|
||
Return number of occurrences of value.
|
||
</Function>
|
||
|
||
#### index
|
||
|
||
<Function id="qiskit_addon_mpf.costs.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.costs.LSE.solve" github="https://github.com/Qiskit/qiskit-addon-mpf/tree/stable/0.3/qiskit_addon_mpf/costs/lse.py#L41-L73" 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.
|
||
* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – if this LSE does not include a row ensuring that $\sum_i x_i == 1$ which is a requirement for valid MPF coefficients.
|
||
|
||
**Return type**
|
||
|
||
[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.2)")
|
||
</Function>
|
||
|
||
#### x
|
||
|
||
<Attribute id="qiskit_addon_mpf.costs.LSE.x" attributeTypeHint="Variable">
|
||
Returns the \$x\$ [`Variable`](https://www.cvxpy.org/api_reference/cvxpy.expressions.html#cvxpy.expressions.variable.Variable "(in CVXPY v1.6)").
|
||
</Attribute>
|
||
</Class>
|
||
|
||
## Optimization problem constructors
|
||
|
||
### setup\_exact\_problem
|
||
|
||
<Function id="qiskit_addon_mpf.costs.setup_exact_problem" github="https://github.com/Qiskit/qiskit-addon-mpf/tree/stable/0.3/qiskit_addon_mpf/costs/exact.py#L22-L74" signature="setup_exact_problem(lse)">
|
||
Construct a [`cvxpy.Problem`](https://www.cvxpy.org/api_reference/cvxpy.problems.html#cvxpy.Problem "(in CVXPY v1.6)") for finding the exact 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.costs.LSE.solve "qiskit_addon_mpf.costs.LSE.solve") method. This additional interface exists to highlight the parallel to the other cost functions provided by this module. It also serves educational purposes for how to approach optimization problems targeting MPF coefficients.
|
||
</Admonition>
|
||
|
||
The optimization problem constructed by this function 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.6)")) of the variables ([`LSE.x`](#qiskit_addon_mpf.costs.LSE.x "qiskit_addon_mpf.costs.LSE.x"))
|
||
|
||
* the constraints correspond to each equation of the [`LSE`](#qiskit_addon_mpf.costs.LSE "qiskit_addon_mpf.costs.LSE"):
|
||
|
||
$$
|
||
\sum_j A_{ij} x_j = b_i
|
||
$$
|
||
|
||
Here is an example:
|
||
|
||
```python
|
||
>>> from qiskit_addon_mpf.costs import setup_exact_problem
|
||
>>> from qiskit_addon_mpf.static import setup_static_lse
|
||
>>> lse = setup_static_lse([1,2,3], order=2, symmetric=True)
|
||
>>> problem, coeffs = setup_exact_problem(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 access 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.costs.LSE "qiskit_addon_mpf.costs.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.6)"), [*Variable*](https://www.cvxpy.org/api_reference/cvxpy.expressions.html#cvxpy.expressions.variable.Variable "(in CVXPY v1.6)")]
|
||
|
||
**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>
|
||
|
||
### setup\_sum\_of\_squares\_problem
|
||
|
||
<Function id="qiskit_addon_mpf.costs.setup_sum_of_squares_problem" github="https://github.com/Qiskit/qiskit-addon-mpf/tree/stable/0.3/qiskit_addon_mpf/costs/sum_of_squares.py#L22-L77" signature="setup_sum_of_squares_problem(lse, *, max_l1_norm=10.0)">
|
||
Construct a [`cvxpy.Problem`](https://www.cvxpy.org/api_reference/cvxpy.problems.html#cvxpy.Problem "(in CVXPY v1.6)") for finding approximate MPF coefficients.
|
||
|
||
The optimization problem constructed by this function 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.6)")) of the distances to an exact solution for all equations of the [`LSE`](#qiskit_addon_mpf.costs.LSE "qiskit_addon_mpf.costs.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.6)")) of the variables is bounded by `max_l1_norm`
|
||
|
||
Here is an example:
|
||
|
||
```python
|
||
>>> from qiskit_addon_mpf.costs import setup_sum_of_squares_problem
|
||
>>> from qiskit_addon_mpf.static import setup_static_lse
|
||
>>> lse = setup_static_lse([1,2,3], order=2, symmetric=True)
|
||
>>> problem, coeffs = setup_sum_of_squares_problem(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 access the expansion coefficients like so:
|
||
|
||
```python
|
||
>>> final_cost = problem.solve()
|
||
>>> print(coeffs.value)
|
||
[ 0.03513467 -1. 1.96486533]
|
||
```
|
||
|
||
**Parameters**
|
||
|
||
* **lse** ([*LSE*](#qiskit_addon_mpf.costs.LSE "qiskit_addon_mpf.costs.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.6)"), [*Variable*](https://www.cvxpy.org/api_reference/cvxpy.expressions.html#cvxpy.expressions.variable.Variable "(in CVXPY v1.6)")]
|
||
|
||
**References**
|
||
|
||
**\[1]: S. Zhuk et al., Phys. Rev. Research 6, 033309 (2024).**
|
||
|
||
[https://journals.aps.org/prresearch/abstract/10.1103/PhysRevResearch.6.033309](https://journals.aps.org/prresearch/abstract/10.1103/PhysRevResearch.6.033309)
|
||
</Function>
|
||
|
||
### setup\_frobenius\_problem
|
||
|
||
<Function id="qiskit_addon_mpf.costs.setup_frobenius_problem" github="https://github.com/Qiskit/qiskit-addon-mpf/tree/stable/0.3/qiskit_addon_mpf/costs/frobenius.py#L22-L126" signature="setup_frobenius_problem(lse, *, max_l1_norm=10.0)">
|
||
Construct a [`cvxpy.Problem`](https://www.cvxpy.org/api_reference/cvxpy.problems.html#cvxpy.Problem "(in CVXPY v1.6)") for finding approximate MPF coefficients.
|
||
|
||
The optimization problem constructed by this function is defined as follows:
|
||
|
||
* the cost function minimizes the following quadratic expression:
|
||
|
||
$$
|
||
1 + x^T A x - 2 x^T b
|
||
$$
|
||
|
||
As shown in \[1] and \[2], this expression arises from the Frobenius norm of the error between an exact time evolution state and a dynamic MPF. As such, taking the [`LSE`](#qiskit_addon_mpf.costs.LSE "qiskit_addon_mpf.costs.LSE") constructed by [`setup_dynamic_lse()`](dynamic#setup_dynamic_lse "qiskit_addon_mpf.dynamic.setup_dynamic_lse") and plugging it into this function will yield Eq. (20) of \[1] (which is identical to Eq. (2) of \[2]), which we repeat below
|
||
|
||
$$
|
||
1 + \sum_{i,j} A_{ij}(t) x_i(t) x_j(t) - 2 \sum_i b_i(t) x_i(t) \, ,
|
||
$$
|
||
|
||
where \$A\$ and \$b\$ of our [`LSE`](#qiskit_addon_mpf.costs.LSE "qiskit_addon_mpf.costs.LSE") correspond to the Gram matrix (\$M\$ in \[1] and \[2]) and the overlap vector (\$L\$ in \[1] and \[2]), respectively. Additionally, we use \$x(t)\$ to denote the MPF variables (or coefficients) rather than \$c\$ in \[1] and \[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.6)")) of the variables is bounded by `max_l1_norm`
|
||
|
||
Below is an example which uses the `lse` object constructed in the example for [`setup_dynamic_lse()`](dynamic#setup_dynamic_lse "qiskit_addon_mpf.dynamic.setup_dynamic_lse").
|
||
|
||
```python
|
||
>>> from qiskit_addon_mpf.costs import setup_frobenius_problem
|
||
>>> problem, coeffs = setup_frobenius_problem(lse, max_l1_norm=3.0)
|
||
>>> print(problem)
|
||
minimize 1.0 + QuadForm(x, [[1.00 1.00]
|
||
[1.00 1.00]]) + -[2.00003171 1.99997911] @ x
|
||
subject to Sum(x, None, False) == 1.0
|
||
norm1(x) <= 3.0
|
||
```
|
||
|
||
You can then solve the problem and access the expansion coefficients like so:
|
||
|
||
```python
|
||
>>> final_cost = problem.solve()
|
||
>>> print(coeffs.value)
|
||
[0.50596416 0.49403584]
|
||
```
|
||
|
||
**Parameters**
|
||
|
||
* **lse** ([*LSE*](#qiskit_addon_mpf.costs.LSE "qiskit_addon_mpf.costs.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.6)"), [*Variable*](https://www.cvxpy.org/api_reference/cvxpy.expressions.html#cvxpy.expressions.variable.Variable "(in CVXPY v1.6)")]
|
||
|
||
**References**
|
||
|
||
**\[1]: S. Zhuk et al., Phys. Rev. Research 6, 033309 (2024).**
|
||
|
||
[https://journals.aps.org/prresearch/abstract/10.1103/PhysRevResearch.6.033309](https://journals.aps.org/prresearch/abstract/10.1103/PhysRevResearch.6.033309)
|
||
|
||
**\[2]: N. Robertson et al., arXiv:2407.17405v2 (2024).**
|
||
|
||
[https://arxiv.org/abs/2407.17405v2](https://arxiv.org/abs/2407.17405v2)
|
||
</Function>
|
||
|