[do not merge] demo new mpf docs

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

@@ -5,6 +5,107 @@
       "title": "API index",
       "url": "/api/qiskit-addon-mpf"
     },
+    {
+      "title": "qiskit_addon_mpf.backends",
+      "url": "/api/qiskit-addon-mpf/backends"
+    },
+    {
+      "title": "qiskit_addon_mpf.backends.quimb_circuit",
+      "children": [
+        {
+          "title": "Module overview",
+          "url": "/api/qiskit-addon-mpf/backends-quimb-circuit"
+        },
+        {
+          "title": "CircuitEvolver",
+          "url": "/api/qiskit-addon-mpf/backends-quimb-circuit-circuit-evolver"
+        },
+        {
+          "title": "CircuitState",
+          "url": "/api/qiskit-addon-mpf/backends-quimb-circuit-circuit-state"
+        }
+      ]
+    },
+    {
+      "title": "qiskit_addon_mpf.backends.quimb_layers",
+      "children": [
+        {
+          "title": "Module overview",
+          "url": "/api/qiskit-addon-mpf/backends-quimb-layers"
+        },
+        {
+          "title": "LayerModel",
+          "url": "/api/qiskit-addon-mpf/backends-quimb-layers-layer-model"
+        },
+        {
+          "title": "LayerwiseEvolver",
+          "url": "/api/qiskit-addon-mpf/backends-quimb-layers-layerwise-evolver"
+        }
+      ]
+    },
+    {
+      "title": "qiskit_addon_mpf.backends.quimb_tebd",
+      "children": [
+        {
+          "title": "Module overview",
+          "url": "/api/qiskit-addon-mpf/backends-quimb-tebd"
+        },
+        {
+          "title": "MPOState",
+          "url": "/api/qiskit-addon-mpf/backends-quimb-tebd-mpo-state"
+        },
+        {
+          "title": "TEBDEvolver",
+          "url": "/api/qiskit-addon-mpf/backends-quimb-tebd-tebd-evolver"
+        }
+      ]
+    },
+    {
+      "title": "qiskit_addon_mpf.backends.tenpy_layers",
+      "children": [
+        {
+          "title": "Module overview",
+          "url": "/api/qiskit-addon-mpf/backends-tenpy-layers"
+        },
+        {
+          "title": "LayerModel",
+          "url": "/api/qiskit-addon-mpf/backends-tenpy-layers-layer-model"
+        },
+        {
+          "title": "LayerwiseEvolver",
+          "url": "/api/qiskit-addon-mpf/backends-tenpy-layers-layerwise-evolver"
+        }
+      ]
+    },
+    {
+      "title": "qiskit_addon_mpf.backends.tenpy_tebd",
+      "children": [
+        {
+          "title": "Module overview",
+          "url": "/api/qiskit-addon-mpf/backends-tenpy-tebd"
+        },
+        {
+          "title": "MPOState",
+          "url": "/api/qiskit-addon-mpf/backends-tenpy-tebd-mpo-state"
+        },
+        {
+          "title": "MPS_neel_state",
+          "url": "/api/qiskit-addon-mpf/backends-tenpy-tebd-mps-neel-state"
+        },
+        {
+          "title": "TEBDEvolver",
+          "url": "/api/qiskit-addon-mpf/backends-tenpy-tebd-tebd-evolver"
+        }
+      ]
+    },
+    {
+      "title": "qiskit_addon_mpf.costs",
+      "url": "/api/qiskit-addon-mpf/costs"
+    },
+    {
+      "title": "qiskit_addon_mpf.dynamic",
+      "url": "/api/qiskit-addon-mpf/dynamic"
+    },
     {
       "title": "qiskit_addon_mpf.static",
       "url": "/api/qiskit-addon-mpf/static"

docs/api/qiskit-addon-mpf/backends-quimb-circuit-circuit-evolver.mdx

@@ -0,0 +1,66 @@
+---
+title: CircuitEvolver (latest version)
+description: API reference for qiskit_addon_mpf.backends.quimb_circuit.CircuitEvolver in the latest version of qiskit-addon-mpf
+in_page_toc_min_heading_level: 1
+python_api_type: class
+python_api_name: qiskit_addon_mpf.backends.quimb_circuit.CircuitEvolver
+---
+
+# CircuitEvolver
+
+<Class id="qiskit_addon_mpf.backends.quimb_circuit.CircuitEvolver" isDedicatedPage={true} github="https://github.com/Qiskit/qiskit-addon-mpf/tree/main/qiskit_addon_mpf/backends/quimb_circuit/evolver.py#L24-L92" signature="CircuitEvolver(evolution_state, circuit, dt)" modifiers="class">
+  Bases: [`Evolver`](backends#evolver "qiskit_addon_mpf.backends.interface.Evolver")
+
+  A time-evolution engine based on quantum circuits.
+
+  This algorithm performs time-evolution by means of successively applying a quantum circuit corresponding to a single Trotter step to its internal state. More specifically, it builds out a tensor network in the [`CircuitState`](backends-quimb-circuit-circuit-state "qiskit_addon_mpf.backends.quimb_circuit.CircuitState"). As required by the [`DynamicMPF`](dynamic#dynamicmpf "qiskit_addon_mpf.dynamic.DynamicMPF") algorithm, it tracks a left- and right-hand side of the time-evolution for computing the overlap of two circuits. Depending on [`conjugate`](#qiskit_addon_mpf.backends.quimb_circuit.CircuitEvolver.conjugate "qiskit_addon_mpf.backends.quimb_circuit.CircuitEvolver.conjugate"), an instance of this engine will apply the quantum gates of its template circuit to the corresponding side (see [`quimb_circuit`](backends-quimb-circuit#module-qiskit_addon_mpf.backends.quimb_circuit "qiskit_addon_mpf.backends.quimb_circuit") for more details).
+
+  Initialize a [`CircuitEvolver`](#qiskit_addon_mpf.backends.quimb_circuit.CircuitEvolver "qiskit_addon_mpf.backends.quimb_circuit.CircuitEvolver") instance.
+
+  **Parameters**
+
+  *   **evolution\_state** ([*CircuitState*](backends-quimb-circuit-circuit-state "qiskit_addon_mpf.backends.quimb_circuit.CircuitState")) – a reference to the time-evolution state.
+  *   **circuit** (*QuantumCircuit*) – the template circuit encoding the time-evolution of a single Trotter step. This circuit **must** be parametrized (see [`Parameter`](/api/qiskit/qiskit.circuit.Parameter "(in Qiskit v1.2)") in place of the Trotter methods time step. This parameter must be named `dt`.
+  *   **dt** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")) – the time step that will be used and later bound to the [`Parameter`](/api/qiskit/qiskit.circuit.Parameter "(in Qiskit v1.2)") of the `circuit` object.
+
+  ## Attributes
+
+  ### conjugate
+
+  <Attribute id="qiskit_addon_mpf.backends.quimb_circuit.CircuitEvolver.conjugate">
+    Returns whether this time-evolver instance acts on the right-hand side.
+  </Attribute>
+
+  ### evolved\_time
+
+  <Attribute id="qiskit_addon_mpf.backends.quimb_circuit.CircuitEvolver.evolved_time">
+    Returns the current evolution time.
+  </Attribute>
+
+  ### evolution\_state
+
+  <Attribute id="qiskit_addon_mpf.backends.quimb_circuit.CircuitEvolver.evolution_state">
+    The time-evolution state (see also [`DynamicMPF.evolution_state`](dynamic#evolution_state "qiskit_addon_mpf.dynamic.DynamicMPF.evolution_state")).
+  </Attribute>
+
+  ### circuit
+
+  <Attribute id="qiskit_addon_mpf.backends.quimb_circuit.CircuitEvolver.circuit">
+    The parameterized [`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)") describing the Trotter step.
+  </Attribute>
+
+  ## Methods
+
+  ### step
+
+  <Function id="qiskit_addon_mpf.backends.quimb_circuit.CircuitEvolver.step" github="https://github.com/Qiskit/qiskit-addon-mpf/tree/main/qiskit_addon_mpf/backends/quimb_circuit/evolver.py#L74-L92" signature="step()">
+    Perform a single time step of TEBD.
+
+    This will apply the gates of the [`circuit`](#qiskit_addon_mpf.backends.quimb_circuit.CircuitEvolver.circuit "qiskit_addon_mpf.backends.quimb_circuit.CircuitEvolver.circuit") to the [`evolution_state`](#qiskit_addon_mpf.backends.quimb_circuit.CircuitEvolver.evolution_state "qiskit_addon_mpf.backends.quimb_circuit.CircuitEvolver.evolution_state"). If [`conjugate`](#qiskit_addon_mpf.backends.quimb_circuit.CircuitEvolver.conjugate "qiskit_addon_mpf.backends.quimb_circuit.CircuitEvolver.conjugate") is `True`, it applies to [`CircuitState.lhs`](backends-quimb-circuit-circuit-state#lhs "qiskit_addon_mpf.backends.quimb_circuit.CircuitState.lhs"), otherwise to [`CircuitState.rhs`](backends-quimb-circuit-circuit-state#rhs "qiskit_addon_mpf.backends.quimb_circuit.CircuitState.rhs").
+
+    **Return type**
+
+    None
+  </Function>
+</Class>
+

docs/api/qiskit-addon-mpf/backends-quimb-circuit-circuit-state.mdx

@@ -0,0 +1,62 @@
+---
+title: CircuitState (latest version)
+description: API reference for qiskit_addon_mpf.backends.quimb_circuit.CircuitState in the latest version of qiskit-addon-mpf
+in_page_toc_min_heading_level: 1
+python_api_type: class
+python_api_name: qiskit_addon_mpf.backends.quimb_circuit.CircuitState
+---
+
+# CircuitState
+
+<Class id="qiskit_addon_mpf.backends.quimb_circuit.CircuitState" isDedicatedPage={true} github="https://github.com/Qiskit/qiskit-addon-mpf/tree/main/qiskit_addon_mpf/backends/quimb_circuit/state.py#L27-L78" signature="CircuitState" modifiers="class">
+  Bases: [`State`](backends#state "qiskit_addon_mpf.backends.interface.State")
+
+  An MPO-like representation of a time-evolution state based on quantum circuits.
+
+  This time-evolution state can be evolved on its left- and right-hand side as required by the [`DynamicMPF`](dynamic#dynamicmpf "qiskit_addon_mpf.dynamic.DynamicMPF") algorithm.
+
+  Initialize a [`CircuitState`](#qiskit_addon_mpf.backends.quimb_circuit.CircuitState "qiskit_addon_mpf.backends.quimb_circuit.CircuitState") instance.
+
+  ## Attributes
+
+  ### lhs
+
+  <Attribute id="qiskit_addon_mpf.backends.quimb_circuit.CircuitState.lhs" attributeTypeHint="Circuit | None">
+    The left-hand side circuit in form of a tensor network.
+  </Attribute>
+
+  ### rhs
+
+  <Attribute id="qiskit_addon_mpf.backends.quimb_circuit.CircuitState.rhs" attributeTypeHint="Circuit | None">
+    The right-hand side circuit in form of a tensor network.
+  </Attribute>
+
+  ## Methods
+
+  ### overlap
+
+  <Function id="qiskit_addon_mpf.backends.quimb_circuit.CircuitState.overlap" github="https://github.com/Qiskit/qiskit-addon-mpf/tree/main/qiskit_addon_mpf/backends/quimb_circuit/state.py#L41-L78" signature="overlap(initial_state)">
+    Compute the overlap of this state with the provided initial state.
+
+    <Admonition title="Warning" type="caution">
+      This implementation only supports instances of [`qiskit.circuit.QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)") for `initial_state`.
+    </Admonition>
+
+    **Parameters**
+
+    **initial\_state** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.13)")) – the initial state with which to compute the overlap.
+
+    **Raises**
+
+    [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.13)") – if the provided initial state has an incompatible type.
+
+    **Returns**
+
+    The overlap of this state with the provided one.
+
+    **Return type**
+
+    [complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.13)")
+  </Function>
+</Class>
+

docs/api/qiskit-addon-mpf/backends-quimb-circuit.mdx

@@ -0,0 +1,87 @@
+---
+title: quimb_circuit (latest version)
+description: API reference for qiskit_addon_mpf.backends.quimb_circuit 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.backends.quimb_circuit
+---
+
+<span id="module-qiskit_addon_mpf.backends.quimb_circuit" />
+
+<span id="quimb-circuit-based-backend-qiskit-addon-mpf-backends-quimb-circuit" />
+
+# Quimb circuit-based backend
+
+`qiskit_addon_mpf.backends.quimb_circuit`
+
+A circuit-based time-evolution backend using [`quimb`](https://quimb.readthedocs.io/en/latest/autoapi/quimb/index.html#module-quimb "(in quimb v1.8)").
+
+<Admonition title="Warning" type="caution">
+  This backend is only available if the optional dependencies have been installed:
+
+  ```python
+  pip install "qiskit-addon-mpf[quimb]"
+  ```
+</Admonition>
+
+|                                                                                                                     |                                                                                 |
+| ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| [`CircuitEvolver`](backends-quimb-circuit-circuit-evolver "qiskit_addon_mpf.backends.quimb_circuit.CircuitEvolver") | A time-evolution engine based on quantum circuits.                              |
+| [`CircuitState`](backends-quimb-circuit-circuit-state "qiskit_addon_mpf.backends.quimb_circuit.CircuitState")       | An MPO-like representation of a time-evolution state based on quantum circuits. |
+
+## Underlying method
+
+Quimb boasts direct support for the simulation of quantum circuits in the form of its tensor-network based [`quimb.tensor.Circuit`](https://quimb.readthedocs.io/en/latest/autoapi/quimb/tensor/index.html#quimb.tensor.Circuit "(in quimb v1.8)") representation. We can leverage this, to bypass any explicit time-evolution algorithm and instead directly encode the time-evolution in a [`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)") and use [`quimb`](https://quimb.readthedocs.io/en/latest/autoapi/quimb/index.html#module-quimb "(in quimb v1.8)") to compute the overlap between two such circuits. For more information, check out their guide on [Quantum Circuits](https://quimb.readthedocs.io/en/latest/tensor-circuit.html "(in quimb v1.8)").
+
+## Code example
+
+This section shows a simple example to get you started with using this backend. The example shows how to create the three factory functions required for the [`setup_dynamic_lse()`](dynamic#setup_dynamic_lse "qiskit_addon_mpf.dynamic.setup_dynamic_lse").
+
+The [`IdentityStateFactory`](dynamic#identitystatefactory "qiskit_addon_mpf.dynamic.IdentityStateFactory") protocol is already fulfilled by the [`CircuitState`](backends-quimb-circuit-circuit-state "qiskit_addon_mpf.backends.quimb_circuit.CircuitState") constructor, rendering the `identity_factory` argument trivial:
+
+```python
+>>> from qiskit_addon_mpf.backends.quimb_circuit import CircuitState
+>>> identity_factory = CircuitState
+```
+
+The setup of the [`CircuitEvolver`](backends-quimb-circuit-circuit-evolver "qiskit_addon_mpf.backends.quimb_circuit.CircuitEvolver") is slightly more involved. It requires a **parametrized** [`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.2)") object as its input where the [`Parameter`](/api/qiskit/qiskit.circuit.Parameter "(in Qiskit v1.2)") should take the place of the Trotter methods time step (`dt`).
+
+To show how such a parametrized Trotter circuit template is constructed, we reuse the same Hamiltonian and second-order Suzuki-Trotter formula as in [`quimb_layers`](backends-quimb-layers#module-qiskit_addon_mpf.backends.quimb_layers "qiskit_addon_mpf.backends.quimb_layers").
+
+```python
+>>> from qiskit.quantum_info import SparsePauliOp
+>>> hamil = SparsePauliOp.from_sparse_list(
+...     [("ZZ", (i, i+1), 1.0) for i in range(0, 9, 2)] +
+...     [("Z", (i,), 0.5) for i in range(10)] +
+...     [("ZZ", (i, i+1), 1.0) for i in range(1, 9, 2)] +
+...     [("X", (i,), 0.25) for i in range(10)],
+...     num_qubits=10,
+... )
+```
+
+But this time, we specify a [`Parameter`](/api/qiskit/qiskit.circuit.Parameter "(in Qiskit v1.2)") as the `time` argument when constructing the actual circuits.
+
+```python
+>>> from functools import partial
+>>> from qiskit.circuit import Parameter
+>>> from qiskit.synthesis import SuzukiTrotter
+>>> from qiskit_addon_mpf.backends.quimb_circuit import CircuitEvolver
+>>> from qiskit_addon_utils.problem_generators import generate_time_evolution_circuit
+>>> dt = Parameter("dt")
+>>> suzuki_2 = generate_time_evolution_circuit(hamil, time=dt, synthesis=SuzukiTrotter(order=2))
+>>> approx_evolver_factory = partial(CircuitEvolver, circuit=suzuki_2)
+```
+
+<Admonition title="Caution" type="note">
+  It is **necessary** that the name of the [`Parameter`](/api/qiskit/qiskit.circuit.Parameter "(in Qiskit v1.2)") is `dt`!
+</Admonition>
+
+We can choose a higher order Trotter formula for the `exact_evolver_factory`. But note, that we must once again use a parametrized circuit, even if we immediately bind its parameter when constructing the `partial` function.
+
+```python
+>>> suzuki_4 = generate_time_evolution_circuit(hamil, time=dt, synthesis=SuzukiTrotter(order=4))
+>>> exact_evolver_factory = partial(CircuitEvolver, circuit=suzuki_4, dt=0.05)
+```
+
+These factory functions may now be used to run the [`setup_dynamic_lse()`](dynamic#setup_dynamic_lse "qiskit_addon_mpf.dynamic.setup_dynamic_lse"). Refer to its documentation for more details on that.
+