[Feature] Implementation of noise protocol.

docs/realistic_sims/index.md

@@ -0,0 +1 @@
+This section describes how to perform realistic simulations in Qadence.

docs/realistic_sims/measurements.md

@@ -0,0 +1 @@
+This section introduces the various measurement protocols.

docs/realistic_sims/mitigation.md

@@ -0,0 +1 @@
+This section introduces mitigation protocols.

docs/realistic_sims/noise.md

@@ -0,0 +1,63 @@
+Running programs on NISQ devices often leads to partially useful results due to the presence of noise.
+In order to perform realistic simulations, a number of noise models are supported in Qadence and
+corresponding error mitigation techniques whenever possible.
+
+## Readout errors
+
+State Preparation and Measurement (SPAM) in the hardware is a major source of noise in the execution of
+quantum programs. Qadence offers to simulate readout errors with the `Noise` protocol to corrupt the output
+samples of a simulation, through execution via a `QuantumModel`:
+
+```python exec="on" source="material-block" session="noise" result="json"
+from qadence import QuantumModel, QuantumCircuit, kron, H, Z
+from qadence import hamiltonian_factory
+from qadence.noise import Noise
+
+# Simple circuit and observable construction.
+block = kron(H(0), Z(1))
+circuit = QuantumCircuit(2, block)
+observable = hamiltonian_factory(circuit.n_qubits, detuning=Z)
+
+# Construct a quantum model.
+model = QuantumModel(circuit=circuit, observable=observable)
+
+# Define a noise model to use.
+noise = Noise(protocol=Noise.READOUT)
+
+# Run noiseless and noisy simulations.
+noiseless_samples = model.sample(n_shots=100)
+noisy_samples = model.sample(noise=noise, n_shots=100)
+
+print(f"noiseless = {noiseless_samples}") # markdown-exec: hide
+print(f"noisy = {noisy_samples}") # markdown-exec: hide
+```
+
+It is possible to pass options to the noise model. In the previous example, a noise matrix is implicitly computed from a
+uniform distribution. The `option` dictionary argument accepts the following options:
+
+- `seed`: defaulted to `None`, for reproducibility purposes
+- `error_probability`: defaulted to 0.1, a bit flip probability
+- `noise_distribution`: defaulted to `WhiteNoise.UNIFORM`, for non-uniform noise distributions
+- `noise_matrix`: defaulted to `None`, if the noise matrix is known from third-party experiments, _i.e._ hardware calibration.
+
+Noisy simulations go hand-in-hand with measurement protocols discussed in the previous [section](measurements.md), to assess the impact of noise on expectation values. In this case, both measurement and noise protocols have to be defined appropriately. Please note that a noise protocol without a measurement protocol will be ignored for expectation values computations.
+
+
+```python exec="on" source="material-block" session="noise" result="json"
+from qadence.measurements import Measurements
+
+# Define a noise model with options.
+options = {"error_probability": 0.01}
+noise = Noise(protocol=Noise.READOUT, options=options)
+
+# Define a tomographical measurement protocol with options.
+options = {"n_shots": 10000}
+measurement = Measurements(protocol=Measurements.TOMOGRAPHY, options=options)
+
+# Run noiseless and noisy simulations.
+noiseless_exp = model.expectation(measurement=measurement)
+noisy_exp = model.expectation(measurement=measurement, noise=noise)
+
+print(f"noiseless = {noiseless_exp}") # markdown-exec: hide
+print(f"noisy = {noisy_exp}") # markdown-exec: hide
+```

mkdocs.yml

@@ -40,6 +40,12 @@ nav:
     - Quantum circuits differentiation: advanced_tutorials/differentiability.md
     - Custom quantum models: advanced_tutorials/custom-models.md
 
+  - Realistic simulations:
+    - realistic_sims/index.md
+    - Measurement protocols: realistic_sims/measurements.md
+    - Simulated errors: realistic_sims/noise.md
+    - Error mitigation: realistic_sims/mitigation.md
+
   - API:
     - Block system: qadence/blocks.md
     - Operations: qadence/operations.md

qadence/__init__.py

@@ -11,11 +11,12 @@
 from .blocks import *
 from .circuit import *
 from .constructors import *
-from .errors import *
+from .exceptions import *
 from .execution import *
 from .measurements import *
 from .ml_tools import *
 from .models import *
+from .noise import *
 from .operations import *
 from .overlap import *
 from .parameters import *
@@ -46,7 +47,8 @@
     ".blocks",
     ".circuit",
     ".constructors",
-    ".errors",
+    ".noise",
+    ".exceptions",
     ".execution",
     ".measurements",
     ".ml_tools",

qadence/backend.py

@@ -22,10 +22,11 @@
 from qadence.circuit import QuantumCircuit
 from qadence.logger import get_logger
 from qadence.measurements import Measurements
+from qadence.noise import Noise
 from qadence.parameters import stringify
 from qadence.types import BackendName, DiffMode, Endianness
 
-logger = get_logger(__name__)
+logger = get_logger(__file__)
 
 
 @dataclass
@@ -167,9 +168,9 @@ def observable(self, observable: AbstractBlock, n_qubits: int) -> ConvertedObser
     def convert(
         self, circuit: QuantumCircuit, observable: list[AbstractBlock] | AbstractBlock | None = None
     ) -> Converted:
-        """Convert an abstract circuit (and optionally and observable) to their native.
+        """Convert an abstract circuit and an optional observable to their native representation.
 
-        representation. Additionally this function constructs an embedding function which maps from
+        Additionally, this function constructs an embedding function which maps from
         user-facing parameters to device parameters (read more on parameter embedding
         [here][qadence.blocks.embedding.embedding]).
         """
@@ -233,6 +234,7 @@ def sample(
         param_values: dict[str, Tensor] = {},
         n_shots: int = 1000,
         state: Tensor | None = None,
+        noise: Noise | None = None,
         endianness: Endianness = Endianness.BIG,
     ) -> list[Counter]:
         """Sample bit strings.
@@ -243,7 +245,8 @@ def sample(
                 [`embedding`][qadence.blocks.embedding.embedding] for more info.
             n_shots: Number of shots to sample.
             state: Initial state.
-            endianness: Endianness of the resulting bitstrings.
+            noise: A noise model to use.
+            endianness: Endianness of the resulting bit strings.
         """
         raise NotImplementedError
 
@@ -277,7 +280,8 @@ def expectation(
         observable: list[ConvertedObservable] | ConvertedObservable,
         param_values: dict[str, Tensor] = {},
         state: Tensor | None = None,
-        protocol: Measurements | None = None,
+        measurement: Measurements | None = None,
+        noise: Noise | None = None,
         endianness: Endianness = Endianness.BIG,
     ) -> Tensor:
         """Compute the expectation value of the `circuit` with the given `observable`.
@@ -287,7 +291,10 @@ def expectation(
             param_values: _**Already embedded**_ parameters of the circuit. See
                 [`embedding`][qadence.blocks.embedding.embedding] for more info.
             state: Initial state.
-            endianness: Endianness of the resulting bitstrings.
+            measurement: Optional measurement protocol. If None, use
+                exact expectation value with a statevector simulator.
+            noise: A noise model to use.
+            endianness: Endianness of the resulting bit strings.
         """
         raise NotImplementedError
 

qadence/backends/braket/backend.py

@@ -15,7 +15,10 @@
 from qadence.backends.utils import to_list_of_dicts
 from qadence.blocks import AbstractBlock, block_to_tensor
 from qadence.circuit import QuantumCircuit
+from qadence.logger import get_logger
 from qadence.measurements import Measurements
+from qadence.noise import Noise
+from qadence.noise.protocols import apply
 from qadence.overlap import overlap_exact
 from qadence.transpile import transpile
 from qadence.types import BackendName
@@ -24,6 +27,8 @@
 from .config import Configuration, default_passes
 from .convert_ops import convert_block
 
+logger = get_logger(__file__)
+
 
 def promote_parameters(parameters: dict[str, Tensor | float]) -> dict[str, float]:
     float_params = {}
@@ -127,6 +132,7 @@ def sample(
         param_values: dict[str, Tensor] = {},
         n_shots: int = 1,
         state: Tensor | None = None,
+        noise: Noise | None = None,
         endianness: Endianness = Endianness.BIG,
     ) -> list[Counter]:
         """Execute the circuit and return samples of the resulting wavefunction."""
@@ -141,6 +147,7 @@ def sample(
             raise NotImplementedError
 
         # loop over all values in the batch
+
         samples = []
         for vals in to_list_of_dicts(param_values):
             final_circuit = self.assign_parameters(circuit, vals)
@@ -150,6 +157,8 @@ def sample(
             from qadence.transpile import invert_endianness
 
             samples = invert_endianness(samples)
+        if noise is not None:
+            samples = apply(noise=noise, samples=samples)
         return samples
 
     def expectation(
@@ -158,9 +167,16 @@ def expectation(
         observable: list[ConvertedObservable] | ConvertedObservable,
         param_values: dict[str, Tensor] = {},
         state: Tensor | None = None,
-        protocol: Measurements | None = None,
+        measurement: Measurements | None = None,
+        noise: Noise | None = None,
         endianness: Endianness = Endianness.BIG,
     ) -> Tensor:
+        # Noise is ignored if measurement protocol is not provided.
+        if noise is not None and measurement is None:
+            logger.warning(
+                f"Errors of type {noise} are not implemented for exact expectation yet. "
+                "This is ignored for now."
+            )
         # Do not flip endianness here because then we would have to reverse the observable
         wfs = self.run(circuit, param_values, state=state, endianness=Endianness.BIG)
 

qadence/backends/braket/convert_ops.py

@@ -24,7 +24,7 @@
 from braket.parametric import FreeParameter
 
 from qadence.blocks import AbstractBlock, CompositeBlock, PrimitiveBlock
-from qadence.errors import NotSupportedError
+from qadence.exceptions import NotSupportedError
 from qadence.operations import OpName
 from qadence.parameters import evaluate
 

qadence/backends/pulser/backend.py

@@ -18,12 +18,14 @@
 from qadence.backends.utils import to_list_of_dicts
 from qadence.blocks import AbstractBlock
 from qadence.circuit import QuantumCircuit
+from qadence.logger import get_logger
 from qadence.measurements import Measurements
+from qadence.noise import Noise
+from qadence.noise.protocols import apply
 from qadence.overlap import overlap_exact
 from qadence.register import Register
 from qadence.transpile import transpile
-from qadence.types import BackendName
-from qadence.utils import Endianness, get_logger
+from qadence.types import BackendName, Endianness
 
 from .channels import GLOBAL_CHANNEL, LOCAL_CHANNEL
 from .cloud import get_client
@@ -240,6 +242,7 @@ def sample(
         param_values: dict[str, Tensor] = {},
         n_shots: int = 1,
         state: Tensor | None = None,
+        noise: Noise | None = None,
         endianness: Endianness = Endianness.BIG,
     ) -> list[Counter]:
         if n_shots < 1:
@@ -257,6 +260,8 @@ def sample(
             from qadence.transpile import invert_endianness
 
             samples = invert_endianness(samples)
+        if noise is not None:
+            samples = apply(noise=noise, samples=samples)
         return samples
 
     def expectation(
@@ -265,9 +270,17 @@ def expectation(
         observable: list[ConvertedObservable] | ConvertedObservable,
         param_values: dict[str, Tensor] = {},
         state: Tensor | None = None,
-        protocol: Measurements | None = None,
+        measurement: Measurements | None = None,
+        noise: Noise | None = None,
         endianness: Endianness = Endianness.BIG,
     ) -> Tensor:
+        # Noise is ignored if measurement protocol is not provided.
+        if noise is not None and measurement is None:
+            logger.warning(
+                f"Errors of type {noise} are not implemented for exact expectation yet. "
+                "This is ignored for now."
+            )
+
         state = self.run(circuit, param_values=param_values, state=state, endianness=endianness)
 
         observables = observable if isinstance(observable, list) else [observable]

qadence/backends/pyqtorch/backend.py

@@ -14,7 +14,10 @@
 from qadence.backends.utils import to_list_of_dicts
 from qadence.blocks import AbstractBlock
 from qadence.circuit import QuantumCircuit
+from qadence.logger import get_logger
 from qadence.measurements import Measurements
+from qadence.noise import Noise
+from qadence.noise.protocols import apply
 from qadence.overlap import overlap_exact
 from qadence.states import zero_state
 from qadence.transpile import (
@@ -28,6 +31,8 @@
 from .config import Configuration, default_passes
 from .convert_ops import convert_block, convert_observable
 
+logger = get_logger(__name__)
+
 
 @dataclass(frozen=True, eq=True)
 class Backend(BackendInterface):
@@ -123,7 +128,8 @@ def _batched_expectation(
         observable: list[ConvertedObservable] | ConvertedObservable,
         param_values: dict[str, Tensor] = {},
         state: Tensor | None = None,
-        protocol: Measurements | None = None,
+        measurement: Measurements | None = None,
+        noise: Noise | None = None,
         endianness: Endianness = Endianness.BIG,
     ) -> Tensor:
         state = self.run(
@@ -147,7 +153,8 @@ def _looped_expectation(
         observable: list[ConvertedObservable] | ConvertedObservable,
         param_values: dict[str, Tensor] = {},
         state: Tensor | None = None,
-        protocol: Measurements | None = None,
+        measurement: Measurements | None = None,
+        noise: Noise | None = None,
         endianness: Endianness = Endianness.BIG,
     ) -> Tensor:
         state = zero_state(circuit.abstract.n_qubits, batch_size=1) if state is None else state
@@ -173,16 +180,24 @@ def expectation(
         observable: list[ConvertedObservable] | ConvertedObservable,
         param_values: dict[str, Tensor] = {},
         state: Tensor | None = None,
-        protocol: Measurements | None = None,
+        measurement: Measurements | None = None,
+        noise: Noise | None = None,
         endianness: Endianness = Endianness.BIG,
     ) -> Tensor:
+        # Noise is ignored if measurement protocol is not provided.
+        if noise is not None and measurement is None:
+            logger.warning(
+                f"Errors of type {noise} are not implemented for exact expectation yet. "
+                "This is ignored for now."
+            )
         fn = self._looped_expectation if self.config.loop_expectation else self._batched_expectation
         return fn(
             circuit=circuit,
             observable=observable,
             param_values=param_values,
             state=state,
-            protocol=protocol,
+            measurement=measurement,
+            noise=noise,
             endianness=endianness,
         )
 
@@ -192,6 +207,7 @@ def sample(
         param_values: dict[str, Tensor] = {},
         n_shots: int = 1,
         state: Tensor | None = None,
+        noise: Noise | None = None,
         endianness: Endianness = Endianness.BIG,
     ) -> list[Counter]:
         if n_shots < 1:
@@ -212,7 +228,7 @@ def _sample(_probs: Tensor, n_shots: int, endianness: Endianness, n_qubits: int)
 
         wf = self.run(circuit=circuit, param_values=param_values, state=state)
         probs = torch.abs(torch.pow(wf, 2))
-        return list(
+        samples = list(
             map(
                 lambda _probs: _sample(
                     _probs=_probs,
@@ -223,6 +239,9 @@ def _sample(_probs: Tensor, n_shots: int, endianness: Endianness, n_qubits: int)
                 probs,
             )
         )
+        if noise is not None:
+            samples = apply(noise=noise, samples=samples)
+        return samples
 
     def assign_parameters(self, circuit: ConvertedCircuit, param_values: dict[str, Tensor]) -> Any:
         raise NotImplementedError