Implementation of the dynamic MPF feature

Co-authored-by: Kate Marshall <kate.marshall@ibm.com>
Co-authored-by: Niall Robertson <niall.robertson@ibm.com>
Co-authored-by: Alberto Baiardi <alberto.baiardi@ibm.com>

README.md

@@ -56,6 +56,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 +100,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://arxiv.org/abs/2306.12569v2), arXiv:2306.12569v2 [quant-ph].
+3. N. Robertson, et al. [Tensor Network enhanced Dynamic Multiproduct Formulas](https://arxiv.org/abs/2407.17405v2), arXiv:2407.17405v2 [quant-ph].
 
 ----------------------------------------------------------------------------------------------------
 

docs/_templates/autosummary/class_without_inherited_members.rst

@@ -0,0 +1,37 @@
+{#
+   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 %}
+  {% if attributes %}
+   .. rubric:: Attributes
+    {% for item in attributes %}
+      {%- if item not in inherited_members %}
+   .. autoattribute:: {{ item }}
+      {%- endif -%}
+    {%- endfor %}
+  {% endif %}
+{% endblock -%}
+
+{% block methods_summary %}
+  {% set wanted_methods = (methods | reject('==', '__init__') | list) %}
+  {% if wanted_methods %}
+   .. rubric:: Methods
+    {% for item in wanted_methods %}
+      {%- if item not in inherited_members %}
+   .. automethod:: {{ item }}
+      {%- endif -%}
+    {%- endfor %}
+  {% endif %}
+{% endblock %}

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

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:

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:

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:

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:

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:

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:

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:

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:

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

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 = "."

docs/index.rst

@@ -28,6 +28,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
 ------------------
 
@@ -55,6 +74,7 @@ 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].
+3. N. Robertson, et al. `Tensor Network enhanced Dynamic Multiproduct Formulas <https://arxiv.org/abs/2407.17405v2>`_, arXiv:2407.17405v2 [quant-ph].
 
 License
 -------

pyproject.toml

@@ -32,14 +32,25 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+quimb = [
+    "quimb>=1.8, <2",
+    "qiskit-quimb",
+]
+tenpy = [
+    "physics-tenpy>=1.0.4, <2",
+]
+dynamic = [
+    "qiskit-addon-mpf[quimb,tenpy]",
+]
 dev = [
     "qiskit-addon-mpf[test,doctest,nbtest,lint,docs]",
     "tox>=4.4.3",
 ]
 basetest = [
-    "ddt>=1.7",
     "pytest>=8.0",
     "pytest-cov>=5.0",
+    "pytest-subtests>=0.13",
+    "qiskit-addon-mpf[dynamic]",
 ]
 test = [
     "qiskit-addon-mpf[basetest]",
@@ -114,7 +125,6 @@ py-version = "3.9"
 disable = ["all"]
 enable = [
     "reimported",
-    "no-self-use",
     "no-else-raise",
     "redefined-argument-from-local",
     "redefined-builtin",

qiskit_addon_mpf/backends/__init__.py

@@ -0,0 +1,64 @@
+# This code is a Qiskit project.
+#
+# (C) Copyright IBM 2024.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""Optional backends for the :class:`.DynamicMPF` algorithm.
+
+.. currentmodule:: qiskit_addon_mpf.backends
+
+Availability
+------------
+
+Whether a certain backend can be used depends on the availability of the underlying tensor network
+library. This can easily be asserted at runtime using the following indicators:
+
+.. autoclass:: HAS_QUIMB
+
+.. autoclass:: HAS_TENPY
+
+Backends
+--------
+
+Depending on the availability (see above), the following backends are available:
+
+.. autosummary::
+   :toctree:
+
+   quimb_tebd
+   quimb_layers
+   quimb_circuit
+   tenpy_tebd
+   tenpy_layers
+
+Interface
+---------
+
+The interface implemented by any one of these optional backends is made up of the following classes:
+
+.. autoclass:: Evolver
+
+.. autoclass:: State
+"""
+
+from qiskit.utils import LazyImportTester as _LazyImportTester
+
+from .interface import Evolver, State
+
+HAS_QUIMB = _LazyImportTester("quimb", install="pip install qiskit-addon-mpf[quimb]")
+"""Indicates whether the optional :external:mod:`quimb` dependency is installed."""
+
+HAS_TENPY = _LazyImportTester("tenpy", install="pip install qiskit-addon-mpf[tenpy]")
+"""Indicates whether the optional :external:mod:`tenpy` dependency is installed."""
+
+__all__ = [
+    "Evolver",
+    "State",
+]