How-to guide for noisy circuit simulation using OBP (#85)

* docs: add a guide on how to simulate circuits using OBP

* test: ensure PauliLindbladErrorInstruction._define is covered

* docs: update the noisy expectation value computation

This updates the how-to guide on simulating using OBP based on feedback
I received offline.

The most significant change is the update to the noisy expectation value
computation section, which now resembles a workflow involving the
`NoiseLearner` (and its returned result) more closely.

* fix: ruff formatting

* Apply suggestions from code review

Co-authored-by: Jen Glick <41485571+jenglick@users.noreply.github.com>

* docs: decrease fake noise model effect

Prior to this commit, the random noise model that was being generated
essentially killed the entire signal, resulting in a near-zero
expectation value. This commit reduces the noise model coefficient scale
to ensure that some signal remains, resulting in an expectation value
~85% of the noiseless one.

---------

Co-authored-by: Jen Glick <41485571+jenglick@users.noreply.github.com>

Author: mrossinek

docs/how_tos/simulating_circuits_with_obp.ipynb

@@ -14,7 +14,9 @@
 
 from __future__ import annotations
 
-from qiskit.circuit import Instruction
+import numpy as np
+from qiskit.circuit import Instruction, QuantumCircuit, QuantumRegister
+from qiskit.quantum_info import PauliList, SparsePauliOp, SuperOp
 from qiskit_ibm_runtime.utils.noise_learner_result import PauliLindbladError
 
 
@@ -42,3 +44,32 @@ def __init__(self, ple: PauliLindbladError):
     def ple(self) -> PauliLindbladError:
         """Returns the internal Pauli-Lindblad error object."""
         return self._ple
+
+    def _define(self) -> None:
+        # Implementation of Instruction._define which populates the definition attribute with a
+        # QuantumCircuit-based representation of this instruction.
+
+        # This implementation is adapted from qiskit_aer.noise.PauliLindbladError
+        chan_z = np.zeros((1, self.num_qubits), dtype=bool)
+        chan_x = np.zeros_like(chan_z)
+        chan_p = np.ones(1, dtype=float)
+        for term_z, term_x, term_r in zip(
+            self.ple.generators.z,
+            self.ple.generators.x,
+            self.ple.rates,
+        ):
+            term_p = 0.5 - 0.5 * np.exp(-2 * term_r)
+            chan_z = np.concatenate([chan_z, np.logical_xor(chan_z, term_z)], axis=0)
+            chan_x = np.concatenate([chan_x, chan_x ^ term_x])
+            chan_p = np.concatenate([(1 - term_p) * chan_p, term_p * chan_p])
+
+        error_op = SparsePauliOp(PauliList.from_symplectic(chan_z, chan_x), chan_p).simplify()
+        chan = SuperOp(np.zeros(2 * [4**self.num_qubits]))
+        for pauli, coeff in zip(error_op.paulis, error_op.coeffs.real):
+            chan += coeff * SuperOp(pauli)
+
+        q = QuantumRegister(self.num_qubits, "q")
+        qc = QuantumCircuit(q, name=self.name)
+        qc.append(chan.to_instruction(), q)
+
+        self.definition = qc

qiskit_addon_obp/utils/noise.py

@@ -0,0 +1,28 @@
+# This code is a Qiskit project.
+#
+# (C) Copyright IBM 2025.
+#
+# 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.
+
+"""Tests the PauliLindbladError noise utilities."""
+
+import unittest
+
+from qiskit import QuantumCircuit
+from qiskit.quantum_info import PauliList
+from qiskit_addon_obp.utils.noise import PauliLindbladErrorInstruction
+from qiskit_ibm_runtime.utils.noise_learner_result import PauliLindbladError
+
+
+class TestPauliLindbladError(unittest.TestCase):
+    def test_ple_definition(self):
+        err = PauliLindbladError(PauliList(["XX", "XY", "ZX"]), [0.1, 0.2, 0.3])
+        inst = PauliLindbladErrorInstruction(err)
+        self.assertTrue(isinstance(inst.definition, QuantumCircuit))
+        self.assertEqual(inst.definition.data[0].operation.name, "kraus")