Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[do not merge] demo new mpf docs #2328

Closed
wants to merge 2 commits into from
Closed

[do not merge] demo new mpf docs #2328

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
35b69c3
[do not merge] demo new mpf docs
Eric-Arellano Nov 15, 2024
ecd173d
Add TocGrouping
Eric-Arellano Nov 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
106 changes: 106 additions & 0 deletions docs/api/qiskit-addon-mpf/_toc.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,112 @@
{
"title": "qiskit_addon_mpf.static",
"url": "/api/qiskit-addon-mpf/static"
},
{
"title": "qiskit_addon_mpf.dynamic",
"url": "/api/qiskit-addon-mpf/dynamic"
},
{
"title": "qiskit_addon_mpf.costs",
"url": "/api/qiskit-addon-mpf/costs"
},
{
"title": "qiskit_addon_mpf.backends",
"children": [
{
"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"
}
]
}
]
}
],
"collapsed": true
Expand Down
66 changes: 66 additions & 0 deletions docs/api/qiskit-addon-mpf/backends-quimb-circuit-circuit-evolver.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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>

62 changes: 62 additions & 0 deletions docs/api/qiskit-addon-mpf/backends-quimb-circuit-circuit-state.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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>

87 changes: 87 additions & 0 deletions docs/api/qiskit-addon-mpf/backends-quimb-circuit.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.

Loading
Loading