Implementation of the dynamic MPF feature (#33)

* Implementation of the dynamic MPF feature Co-authored-by: Kate Marshall <[email protected]> Co-authored-by: Max Rossmannek <[email protected]> Co-authored-by: Niall Robertson <[email protected]> Co-authored-by: Alberto Baiardi <[email protected]> * Fix issue with empty attributes section * docs: some minor fixes based on offline review Co-authored-by: Kate Marshall <[email protected]> * docs: update reference after its peer-review publication * docs: update module overview in landing pages * docs: attempt to fix alert rendering * Revert "docs: attempt to fix alert rendering" This reverts commit 32091cb. * fix: close div in README --------- Co-authored-by: Kate Marshall <[email protected]> Co-authored-by: Kate Marshall <[email protected]> Co-authored-by: Niall Robertson <[email protected]> Co-authored-by: Alberto Baiardi <[email protected]> Co-authored-by: Eric Arellano <[email protected]>
Qiskit · Nov 21, 2024 · 2bd6331 · 2bd6331
1 parent c999a9f
commit 2bd6331
Show file tree

Hide file tree

Showing 68 changed files with 4,636 additions and 371 deletions.
diff --git a/README.md b/README.md
@@ -12,6 +12,7 @@
   [![Downloads](https://img.shields.io/pypi/dm/qiskit-addon-mpf.svg?label=Downloads)](https://pypi.org/project/qiskit-addon-mpf/)
   [![Tests](https://github.com/Qiskit/qiskit-addon-mpf/actions/workflows/test_latest_versions.yml/badge.svg)](https://github.com/Qiskit/qiskit-addon-mpf/actions/workflows/test_latest_versions.yml)
   [![Coverage](https://coveralls.io/repos/github/Qiskit/qiskit-addon-mpf/badge.svg?branch=main)](https://coveralls.io/github/Qiskit/qiskit-addon-mpf?branch=main)
+</div>
 
 # Qiskit addon: multi-product formulas (MPF)
 
@@ -34,9 +35,10 @@
 This package contains the Qiskit addon for multi-product formulas (MPFs).
 These can be used to reduce the Trotter error of Hamiltonian dynamics.
 
-This package currently contains the following submodules:
+This package currently contains the following main entry points for users:
 
 - `qiskit_addon_mpf.static` for working with static MPFs [1-2](#references)
+- `qiskit_addon_mpf.dynamic` for working with dynamic MPFs [2-3](#references)
 
 ----------------------------------------------------------------------------------------------------
 
@@ -56,6 +58,21 @@ pip install 'qiskit-addon-mpf'
 
 For more installation information refer to these [installation instructions](docs/install.rst).
 
+#### Optional dependencies
+
+The `qiskit-addon-mpf` package has a number of optional dependencies which enable certain features.
+The dynamic MPF feature (see [2-3](#references)) is one such example.
+You can install the related optional dependencies like so:
+
+```bash
+pip install 'qiskit-addon-mpf[dynamic]'
+```
+
+> [!IMPORTANT]
+> The optional dependency [TeNPy](https://github.com/tenpy/tenpy) was previously offered under a GPLv3 license.
+> As of the release of [v1.0.4](https://github.com/tenpy/tenpy/releases/tag/v1.0.4) on October 2nd, 2024, it has been offered under the Apache v2 license.
+> The license of this package is only compatible with Apache-licensed versions of TeNPy.
+
 ----------------------------------------------------------------------------------------------------
 
 ### Deprecation Policy
@@ -85,7 +102,8 @@ We use [GitHub issues](https://github.com/Qiskit/qiskit-addon-mpf/issues/new/cho
 ### References
 
 1. A. Carrera Vazquez, D. J. Egger, D. Ochsner, and S. Wörner, [Well-conditioned multi-product formulas for hardware-friendly Hamiltonian simulation](https://quantum-journal.org/papers/q-2023-07-25-1067/), Quantum 7, 1067 (2023).
-2. S. Zhuk, N. Robertson, and S. Bravyi, [Trotter error bounds and dynamic multi-product formulas for Hamiltonian simulation](https://arxiv.org/abs/2306.12569v2), arXiv:2306.12569 [quant-ph].
+2. S. Zhuk, N. Robertson, and S. Bravyi, [Trotter error bounds and dynamic multi-product formulas for Hamiltonian simulation](https://journals.aps.org/prresearch/abstract/10.1103/PhysRevResearch.6.033309), Phys. Rev. Research 6, 033309 (2024).
+3. N. Robertson, et al. [Tensor Network enhanced Dynamic Multiproduct Formulas](https://arxiv.org/abs/2407.17405v2), arXiv:2407.17405v2 [quant-ph].
 
 ----------------------------------------------------------------------------------------------------
 

diff --git a/docs/_templates/autosummary/class_without_inherited_members.rst b/docs/_templates/autosummary/class_without_inherited_members.rst
@@ -0,0 +1,34 @@
+{#
+   We show all the class's methods and attributes on the same page. By default, we document
+   all methods, including those defined by parent classes.
+-#}
+
+{{ objname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:
+   :show-inheritance:
+
+{% block attributes_summary %}
+  {% set wanted_attributes = (attributes | reject('in', inherited_members) | list) %}
+  {% if wanted_attributes %}
+   .. rubric:: Attributes
+    {% for item in wanted_attributes %}
+   .. autoattribute:: {{ item }}
+    {%- endfor %}
+  {% endif %}
+{% endblock -%}
+
+{% block methods_summary %}
+  {% set wanted_methods = (methods | reject('==', '__init__') | reject('in', inherited_members) | list) %}
+  {% if wanted_methods %}
+   .. rubric:: Methods
+    {% for item in wanted_methods %}
+   .. automethod:: {{ item }}
+    {%- endfor %}
+  {% endif %}
+{% endblock %}
diff --git a/docs/apidocs/index.rst b/docs/apidocs/index.rst
@@ -6,3 +6,6 @@
    :maxdepth: 1
 
    qiskit_addon_mpf.static
+   qiskit_addon_mpf.dynamic
+   qiskit_addon_mpf.costs
+   qiskit_addon_mpf.backends
diff --git a/docs/apidocs/qiskit_addon_mpf.backends.quimb_circuit.rst b/docs/apidocs/qiskit_addon_mpf.backends.quimb_circuit.rst
@@ -0,0 +1,8 @@
+============================================================================
+Quimb circuit-based backend (:mod:`qiskit_addon_mpf.backends.quimb_circuit`)
+============================================================================
+
+.. automodule:: qiskit_addon_mpf.backends.quimb_circuit
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:
diff --git a/docs/apidocs/qiskit_addon_mpf.backends.quimb_layers.rst b/docs/apidocs/qiskit_addon_mpf.backends.quimb_layers.rst
@@ -0,0 +1,8 @@
+=========================================================================
+Quimb layer-based backend (:mod:`qiskit_addon_mpf.backends.quimb_layers`)
+=========================================================================
+
+.. automodule:: qiskit_addon_mpf.backends.quimb_layers
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:
diff --git a/docs/apidocs/qiskit_addon_mpf.backends.quimb_tebd.rst b/docs/apidocs/qiskit_addon_mpf.backends.quimb_tebd.rst
@@ -0,0 +1,8 @@
+================================================================
+Quimb TEBD backend (:mod:`qiskit_addon_mpf.backends.quimb_tebd`)
+================================================================
+
+.. automodule:: qiskit_addon_mpf.backends.quimb_tebd
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:
diff --git a/docs/apidocs/qiskit_addon_mpf.backends.rst b/docs/apidocs/qiskit_addon_mpf.backends.rst
@@ -0,0 +1,8 @@
+===========================================
+Backends (:mod:`qiskit_addon_mpf.backends`)
+===========================================
+
+.. automodule:: qiskit_addon_mpf.backends
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:
diff --git a/docs/apidocs/qiskit_addon_mpf.backends.tenpy_layers.rst b/docs/apidocs/qiskit_addon_mpf.backends.tenpy_layers.rst
@@ -0,0 +1,8 @@
+=========================================================================
+TeNPy layer-based backend (:mod:`qiskit_addon_mpf.backends.tenpy_layers`)
+=========================================================================
+
+.. automodule:: qiskit_addon_mpf.backends.tenpy_layers
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:
diff --git a/docs/apidocs/qiskit_addon_mpf.backends.tenpy_tebd.rst b/docs/apidocs/qiskit_addon_mpf.backends.tenpy_tebd.rst
@@ -0,0 +1,8 @@
+================================================================
+TeNPy TEBD backend (:mod:`qiskit_addon_mpf.backends.tenpy_tebd`)
+================================================================
+
+.. automodule:: qiskit_addon_mpf.backends.tenpy_tebd
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:
diff --git a/docs/apidocs/qiskit_addon_mpf.costs.rst b/docs/apidocs/qiskit_addon_mpf.costs.rst
@@ -0,0 +1,8 @@
+==============================================
+Cost Functions (:mod:`qiskit_addon_mpf.costs`)
+==============================================
+
+.. automodule:: qiskit_addon_mpf.costs
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:
diff --git a/docs/apidocs/qiskit_addon_mpf.dynamic.rst b/docs/apidocs/qiskit_addon_mpf.dynamic.rst
@@ -0,0 +1,8 @@
+==============================================
+Dynamic MPFs (:mod:`qiskit_addon_mpf.dynamic`)
+==============================================
+
+.. automodule:: qiskit_addon_mpf.dynamic
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:
diff --git a/docs/apidocs/qiskit_addon_mpf.static.rst b/docs/apidocs/qiskit_addon_mpf.static.rst
@@ -6,21 +6,3 @@ Static MPFs (:mod:`qiskit_addon_mpf.static`)
    :no-members:
    :no-inherited-members:
    :no-special-members:
-
-.. currentmodule:: qiskit_addon_mpf.static
-
-Linear system of equations utilities
-------------------------------------
-
-.. autoclass:: LSE   
-.. autofunction:: setup_lse
-
-Exact static MPF coefficients
------------------------------
-
-.. autofunction:: setup_exact_model
-
-Approximate static MPF coefficients
------------------------------------
-
-.. autofunction:: setup_approximate_model
diff --git a/docs/conf.py b/docs/conf.py
@@ -107,6 +107,8 @@
     "qiskit": ("https://docs.quantum.ibm.com/api/qiskit/", None),
     "rustworkx": ("https://www.rustworkx.org/", None),
     "qiskit_addon_utils": ("https://qiskit.github.io/qiskit-addon-utils/", None),
+    "quimb": ("https://quimb.readthedocs.io/en/latest/", None),
+    "tenpy": ("https://tenpy.readthedocs.io/en/latest/", None),
 }
 
 plot_working_directory = "."

diff --git a/docs/explanations/mpf_stability.ipynb b/docs/explanations/mpf_stability.ipynb
@@ -17,7 +17,7 @@
     "Over in the guide [How to choose the Trotter steps for an MPF](https://qiskit.github.io/qiskit-addon-mpf/how_tos/choose_trotter_steps.html) we introduced a heuristic that limits the **smallest** $k_j$ value ($k_{\\text{min}}$) based on the total evolution time, $t$, that we would like to reach.\n",
     "In particular, we state that $t/k_{\\text{min}} \\lt 1$ must be satisfied (noting that $t/k_{\\text{min}} \\leq 1$ empirically seems to work fine, too).\n",
     "\n",
-    "On this page, we will analyze the behavior of MPFs is not guaranteed to work well, when this constraint gets violated."
+    "On this page, we will analyze when the behavior of MPFs is not guaranteed to work well, such as when this constraint gets violated."
    ]
   },
   {

diff --git a/docs/how_tos/choose_trotter_steps.ipynb b/docs/how_tos/choose_trotter_steps.ipynb
@@ -76,7 +76,7 @@
     "\n",
     "where $\\chi$ is the order of our individual product formulas.\n",
     "\n",
-    "[Zhuk et al., 2023]: https://arxiv.org/abs/2306.12569"
+    "[Zhuk et al., 2023]: https://journals.aps.org/prresearch/abstract/10.1103/PhysRevResearch.6.033309"
    ]
   },
   {
@@ -93,7 +93,7 @@
    "source": [
     "### Preparing our LSE\n",
     "\n",
-    "In a first step, we prepare the LSE, $Ax=b$, leveraging a feature of the [setup_lse](https://qiskit.github.io/qiskit-addon-mpf/stubs/qiskit_addon_mpf.static.setup_lse.html) function that allows us to use a [cvxpy.Parameter](https://www.cvxpy.org/api_reference/cvxpy.expressions.html#parameter) object for our $k_j$ values."
+    "In a first step, we prepare the LSE, $Ax=b$, leveraging a feature of the [setup_static_lse](https://qiskit.github.io/qiskit-addon-mpf/stubs/qiskit_addon_mpf.static.setup_static_lse.html) function that allows us to use a [cvxpy.Parameter](https://www.cvxpy.org/api_reference/cvxpy.expressions.html#parameter) object for our $k_j$ values."
    ]
   },
   {
@@ -133,10 +133,10 @@
    "outputs": [],
    "source": [
     "import cvxpy as cp\n",
-    "from qiskit_addon_mpf.static import setup_lse\n",
+    "from qiskit_addon_mpf.static import setup_static_lse\n",
     "\n",
     "ks = cp.Parameter(3, integer=True)\n",
-    "lse = setup_lse(ks, order=order, symmetric=symmetric)"
+    "lse = setup_static_lse(ks, order=order, symmetric=symmetric)"
    ]
   },
   {
@@ -208,7 +208,7 @@
    "source": [
     "Finally, we sort our $k_j$ by the re-weighted L1-norm presented by [Zhuk et al., 2023]:\n",
     "\n",
-    "[Zhuk et al., 2023]: https://arxiv.org/abs/2306.12569"
+    "[Zhuk et al., 2023]: https://journals.aps.org/prresearch/abstract/10.1103/PhysRevResearch.6.033309"
    ]
   },
   {

diff --git a/docs/how_tos/using_approximate_model.ipynb b/docs/how_tos/using_approximate_model.ipynb
@@ -14,7 +14,7 @@
    "source": [
     "# How to use the approximate model\n",
     "\n",
-    "You have already seen a first example of the [setup_approximate_model](https://qiskit.github.io/qiskit-addon-mpf/stubs/qiskit_addon_mpf.static.setup_approximate_model.html) function in the [Getting started](https://qiskit.github.io/qiskit-addon-mpf/tutorials/01_getting_started.html) tutorial.\n",
+    "You have already seen a first example of the [setup_sum_of_squares_problem](https://qiskit.github.io/qiskit-addon-mpf/stubs/qiskit_addon_mpf.costs.setup_sum_of_squares_problem.html) function in the [Getting started](https://qiskit.github.io/qiskit-addon-mpf/tutorials/01_getting_started.html) tutorial.\n",
     "In this guide, we are going to revisit that function in more detail."
    ]
   },
@@ -92,7 +92,7 @@
    "source": [
     "## Choosing $k_j$\n",
     "\n",
-    "In this guide, we are going to focus on the tweaks that we can apply to the [cvxpy.Problem](https://www.cvxpy.org/api_reference/cvxpy.problems.html#cvxpy.Problem) and its solver that are returned by the [setup_approximate_model](https://qiskit.github.io/qiskit-addon-mpf/stubs/qiskit_addon_mpf.static.setup_approximate_model.html). Therefore, we are not concerned with choosing any specific $k_j$ values and can simply reuse the ones from the [Getting started](https://qiskit.github.io/qiskit-addon-mpf/tutorials/01_getting_started.html) tutorial."
+    "In this guide, we are going to focus on the tweaks that we can apply to the [cvxpy.Problem](https://www.cvxpy.org/api_reference/cvxpy.problems.html#cvxpy.Problem) and its solver that are returned by the [setup_sum_of_squares_problem](https://qiskit.github.io/qiskit-addon-mpf/stubs/qiskit_addon_mpf.costs.setup_sum_of_squares_problem.html). Therefore, we are not concerned with choosing any specific $k_j$ values and can simply reuse the ones from the [Getting started](https://qiskit.github.io/qiskit-addon-mpf/tutorials/01_getting_started.html) tutorial."
    ]
   },
   {
@@ -135,9 +135,9 @@
    },
    "outputs": [],
    "source": [
-    "from qiskit_addon_mpf.static import setup_lse\n",
+    "from qiskit_addon_mpf.static import setup_static_lse\n",
     "\n",
-    "lse = setup_lse(trotter_steps, order=2, symmetric=True)"
+    "lse = setup_static_lse(trotter_steps, order=2, symmetric=True)"
    ]
   },
   {
@@ -222,14 +222,14 @@
     "\n",
     "Now, we will construct the approximate model.\n",
     "The idea of using approximate solutions $\\tilde{x}$ in order to ensure a smaller L1-norm was proposed by [Zhuk et al., 2023].\n",
-    "The model is already explained in detail in the API documentation of [setup_approximate_model](https://qiskit.github.io/qiskit-addon-mpf/stubs/qiskit_addon_mpf.static.setup_approximate_model.html) so we refrain from repeating it here.\n",
+    "The model is already explained in detail in the API documentation of [setup_sum_of_squares_problem](https://qiskit.github.io/qiskit-addon-mpf/stubs/qiskit_addon_mpf.costs.setup_sum_of_squares_problem.html) so we refrain from repeating it here.\n",
     "Suffice to say, that the model consists of two constraints which ensure that the coefficients, $\\tilde{x}$, sum to $1$ and it enforces their L1-norm to be smaller than the user-provided `max_l1_norm` value.\n",
     "The optimization objective is to minimize the deviation of $A\\tilde{x}=b$.\n",
     "\n",
     "We can see all of this in the output below.\n",
-    "Here, we are setting `max_l1_norm=3` because we already know that the L1-norm of the exact solution is approximately $3.4$ and we want to find a $\\tilde{x}$ that has a smaller L1-norm (since otherwise this exercise would be rather pointless).\n",
+    "Here, we are setting `max_l1_norm=3` because we already know that the L1-norm of the exact solution is approximately $3.4$ and we want to find a $\\tilde{x}$ that has a smaller L1-norm.\n",
     "\n",
-    "[Zhuk et al., 2023]: https://arxiv.org/abs/2306.12569"
+    "[Zhuk et al., 2023]: https://journals.aps.org/prresearch/abstract/10.1103/PhysRevResearch.6.033309"
    ]
   },
   {
@@ -255,9 +255,9 @@
     }
    ],
    "source": [
-    "from qiskit_addon_mpf.static import setup_approximate_model\n",
+    "from qiskit_addon_mpf.costs import setup_sum_of_squares_problem\n",
     "\n",
-    "model, coeff_var = setup_approximate_model(lse, max_l1_norm=3)\n",
+    "model, coeff_var = setup_sum_of_squares_problem(lse, max_l1_norm=3)\n",
     "print(model)"
    ]
   },

diff --git a/docs/index.rst b/docs/index.rst
@@ -7,9 +7,10 @@ Qiskit addon: multi-product formulas (MPF)
 This package contains the Qiskit addon for multi-product formulas (MPFs).
 These can be used to reduce the Trotter error of Hamiltonian dynamics.
 
-This package currently contains the following submodules:
+This package currently contains the following main entry points for users:
 
 - ``qiskit_addon_mpf.static`` for working with static MPFs [`1-2 <#references>`_].
+- ``qiskit_addon_mpf.dynamic`` for working with dynamic MPFs [`2-3 <#references>`_].
 
 Documentation
 -------------
@@ -28,6 +29,25 @@ We encourage installing this package via ``pip``, when possible:
 
 For more installation information refer to the `installation instructions <install.rst>`_ in the documentation.
 
+Optional dependencies
++++++++++++++++++++++
+
+The ``qiskit-addon-mpf`` package has a number of optional dependencies which enable certain features.
+The dynamic MPF feature (see [`2-3 <#references>`_]) is one such example.
+You can install the related optional dependencies like so:
+
+.. code-block:: bash
+
+    pip install 'qiskit-addon-mpf[dynamic]'
+
+.. caution::
+   The optional dependency `TeNPy <https://github.com/tenpy/tenpy>`_ was previously offered under a
+   GPLv3 license.
+   As of the release of `v1.0.4 <https://github.com/tenpy/tenpy/releases/tag/v1.0.4>`_ on October
+   2nd, 2024, it has been offered under the Apache v2 license.
+   The license of this package is only compatible with Apache-licensed versions of TeNPy.
+
+
 Deprecation Policy
 ------------------
 
@@ -54,7 +74,8 @@ References
 ----------
 
 1. A. Carrera Vazquez, D. J. Egger, D. Ochsner, and S. Wörner, `Well-conditioned multi-product formulas for hardware-friendly Hamiltonian simulation <https://quantum-journal.org/papers/q-2023-07-25-1067/>`_, Quantum 7, 1067 (2023).
-2. S. Zhuk, N. Robertson, and S. Bravyi, `Trotter error bounds and dynamic multi-product formulas for Hamiltonian simulation <https://arxiv.org/abs/2306.12569v2>`_, arXiv:2306.12569 [quant-ph].
+2. S. Zhuk, N. Robertson, and S. Bravyi, `Trotter error bounds and dynamic multi-product formulas for Hamiltonian simulation <https://journals.aps.org/prresearch/abstract/10.1103/PhysRevResearch.6.033309>`_, Phys. Rev. Research 6, 033309 (2024).
+3. N. Robertson, et al. `Tensor Network enhanced Dynamic Multiproduct Formulas <https://arxiv.org/abs/2407.17405v2>`_, arXiv:2407.17405v2 [quant-ph].
 
 License
 -------

diff --git a/docs/install.rst b/docs/install.rst
@@ -56,7 +56,7 @@ If so, the first step is to clone the ``qiskit-addon-mpf`` repository.
 
     git clone [email protected]:Qiskit/qiskit-addon-mpf.git
 
-Next, upgrade pip and enter the repository.
+Next, upgrade ``pip`` and enter the repository.
 
 .. code:: sh