Custom boolean functions for supporting noise models

doc/code/qml_noise.rst

@@ -0,0 +1,90 @@
+qml.noise
+=========
+
+This module contains the functionality for building and manipulating noise models.
+
+Overview
+--------
+
+In PennyLane, noise models are defined via a mapping of conditions defined as ``Conditionals``
+to functions specified as ``Callables``, along with some additional noise-related metadata.
+
+::
+
+    NoiseModel: ({Conditionals --> Callables},  metadata)
+
+Each ``Conditional`` evaluates the gate operations in the quantum circuit based on some
+condition of its attributes (e.g., type, parameters, wires, etc.) and use the corresponding
+``Callable`` to apply the noise operations, using the user-provided metadata (e.g., hardware
+topologies or relaxation times), whenever the condition results true.
+
+.. currentmodule:: pennylane.noise
+
+Conditional Constructors
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. currentmodule:: pennylane.noise.conditionals
+
+.. autosummary::
+    :toctree: api
+
+    ~op_eq
+    ~op_in
+    ~wires_eq
+    ~wires_in
+
+Arbitrary conditionals can also be defined by wrapping the functional form
+of custom conditions with the following decorator:
+
+.. currentmodule:: pennylane
+
+.. autosummary::
+    :toctree: api
+
+    ~BooleanFn
+
+.. note::
+
+    Conditionals built via these constructors or decorator can be combined using
+    standard bit-wise operators, such as ``&``, ``|``, ``^``, or ``~``. The resulting
+    combination will still behave like a single conditional and store the individual
+    components in the ``operands`` attribute. As Python will evaluate the expression
+    in the same order, i.e., left to right, the order of composition could matter,
+    even though bitwise operations are symmetric by definition.
+
+Callable Constructor
+^^^^^^^^^^^^^^^^^^^^
+
+.. currentmodule:: pennylane.noise.conditionals
+
+.. autosummary::
+    :toctree: api
+
+    ~partial_wires
+
+.. note::
+
+    The signature of any user-defined callable must be -
+    ``callable(op: Operation, **kwargs) -> None``, i.e., it accepts
+    an operation and some metadata-based keyword arguments. It should
+    then let one queue the noisy gates corresponding to that operation
+    similar to a quantum function but without returning any measurements.
+
+Conditional Classes
+^^^^^^^^^^^^^^^^^^^
+
+.. currentmodule:: pennylane.noise.conditionals
+
+.. autosummary::
+    :toctree: api
+
+    ~OpEq
+    ~OpIn
+    ~WiresEq
+    ~WiresIn
+
+Class Inheritence Diagram
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. inheritance-diagram:: pennylane.noise.conditionals
+    :parts: 1

doc/index.rst

@@ -201,6 +201,7 @@ PennyLane is **free** and **open source**, released under the Apache License, Ve
    code/qml_kernels
    code/qml_logging
    code/qml_math
+   code/qml_noise
    code/qml_numpy
    code/qml_ops_op_math
    code/qml_pauli

doc/releases/changelog-dev.md

@@ -47,6 +47,8 @@
 * The `default.tensor` device is introduced to perform tensor network simulation of a quantum circuit.
   [(#5699)](https://github.com/PennyLaneAI/pennylane/pull/5699)
 
+* A new `qml.noise` module which contains utililty functions for building `NoiseModels`.
+  [(#5674)](https://github.com/PennyLaneAI/pennylane/pull/5674)
 
 <h3>Improvements 🛠</h3>
 
@@ -366,6 +368,7 @@
 This release contains contributions from (in alphabetical order):
 
 Guillermo Alonso-Linaje,
+Utkarsh Azad,
 Lillian M. A. Frederiksen,
 Gabriel Bottrill,
 Astral Cai,

pennylane/__init__.py

@@ -138,6 +138,7 @@
 import pennylane.compiler
 
 import pennylane.data
+import pennylane.noise
 
 from packaging.specifiers import SpecifierSet
 from packaging.version import Version

pennylane/boolean_fn.py

@@ -1,4 +1,4 @@
-# Copyright 2018-2021 Xanadu Quantum Technologies Inc.
+# Copyright 2018-2024 Xanadu Quantum Technologies Inc.
 
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -19,13 +19,14 @@
 import functools
 
 
+# pylint: disable=unnecessary-lambda
 class BooleanFn:
     r"""Wrapper for simple callables with boolean output that can be
     manipulated and combined with bit-wise operators.
 
     Args:
-        fn (callable): Function to be wrapped. It must accept a single
-            argument, and must return a boolean.
+        fn (callable): Function to be wrapped. It can accept any number
+            of arguments, and must return a boolean.
 
     **Example**
 
@@ -77,18 +78,132 @@ class BooleanFn:
 
     """
 
-    def __init__(self, fn):
+    def __init__(self, fn, name=None):
         self.fn = fn
+        self.name = name or self.fn.__name__
         functools.update_wrapper(self, fn)
 
     def __and__(self, other):
-        return BooleanFn(lambda obj: self.fn(obj) and other.fn(obj))
+        return And(self, other)
 
     def __or__(self, other):
-        return BooleanFn(lambda obj: self.fn(obj) or other.fn(obj))
+        return Or(self, other)
+
+    def __xor__(self, other):
+        return Xor(self, other)
 
     def __invert__(self):
-        return BooleanFn(lambda obj: not self.fn(obj))
+        return Not(self)
+
+    def __call__(self, *args, **kwargs):
+        return self.fn(*args, **kwargs)
+
+    def __repr__(self):
+        return f"BooleanFn({self.name})" if not (self.bitwise or self.conditional) else self.name
+
+    @property
+    def bitwise(self):
+        """Determine whether wrapped callable performs a bit-wise operation or not.
+        This checks for the ``operands`` attribute that should be defined by it."""
+        return bool(getattr(self, "operands", tuple()))
+
+    @property
+    def conditional(self):
+        """Determine whether wrapped callable is for a conditional or not.
+        This checks for the ``condition`` attribute that should be defined by it."""
+        return bool(getattr(self, "condition", None))
+
+
+class And(BooleanFn):
+    """Developer facing class for implemeting bit-wise ``AND`` for callables
+    wrapped up with :class:`BooleanFn <pennylane.BooleanFn>`.
+
+    Args:
+        left (~.BooleanFn): Left operand in the bit-wise expression.
+        right (~.BooleanFn): Right operand in the bit-wise expression.
+    """
+
+    def __init__(self, left, right):
+        self.operands = (left, right)
+
+        if any(getattr(opr, "condition", None) for opr in self.operands):
+            self.condition = tuple(getattr(opr, "condition", ()) for opr in self.operands)
+
+        super().__init__(
+            lambda *args, **kwargs: left(*args, **kwargs) and right(*args, **kwargs),
+            f"And({left.name}, {right.name})",
+        )
+
+    def __str__(self):
+        return f"{self.operands[0].name} & {self.operands[1].name}"
+
+
+class Or(BooleanFn):
+    """Developer facing class for implemeting bit-wise ``OR`` for callables
+    wrapped up with :class:`BooleanFn <pennylane.BooleanFn>`.
+
+    Args:
+        left (~.BooleanFn): Left operand in the bit-wise expression.
+        right (~.BooleanFn): Right operand in the bit-wise expression.
+    """
+
+    def __init__(self, left, right):
+        self.operands = (left, right)
+
+        if any(getattr(opr, "condition", None) for opr in self.operands):
+            self.condition = tuple(getattr(opr, "condition", ()) for opr in self.operands)
+
+        super().__init__(
+            lambda *args, **kwargs: left(*args, **kwargs) or right(*args, **kwargs),
+            f"Or({left.name}, {right.name})",
+        )
+
+    def __str__(self):
+        return f"{self.operands[0].name} | {self.operands[1].name}"
+
+
+class Xor(BooleanFn):
+    """Developer facing class for implemeting bit-wise ``XOR`` for callables
+    wrapped up with :class:`BooleanFn <pennylane.BooleanFn>`.
+
+    Args:
+        left (~.BooleanFn): Left operand in the bit-wise expression.
+        right (~.BooleanFn): Right operand in the bit-wise expression.
+    """
+
+    def __init__(self, left, right):
+        self.operands = (left, right)
+
+        if any(getattr(opr, "condition", None) for opr in self.operands):
+            self.condition = tuple(getattr(opr, "condition", ()) for opr in self.operands)
+
+        super().__init__(
+            lambda *args, **kwargs: left(*args, **kwargs) ^ right(*args, **kwargs),
+            f"Xor({left.name}, {right.name})",
+        )
+
+    def __str__(self):
+        return f"{self.operands[0].name} ^ {self.operands[1].name}"
+
+
+class Not(BooleanFn):
+    """Developer facing class for implemeting bit-wise ``NOT`` for callables
+    wrapped up with :class:`BooleanFn <pennylane.BooleanFn>`.
+
+    Args:
+        left (~.BooleanFn): Left operand in the bit-wise expression.
+    """
+
+    def __init__(self, left):
+        self.operands = (left,)
+
+        if any(getattr(opr, "condition", None) for opr in self.operands):
+            self.condition = tuple(getattr(opr, "condition", ()) for opr in self.operands)
+
+        super().__init__(
+            lambda *args, **kwargs: not left(*args, **kwargs),
+            f"Not({left.name})",
+        )
 
-    def __call__(self, obj):
-        return self.fn(obj)
+    def __str__(self):
+        return f"~{self.operands[0].name}"

pennylane/noise/__init__.py

@@ -0,0 +1,16 @@
+# Copyright 2018-2024 Xanadu Quantum Technologies Inc.
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""This module contains the functionality to work with noise models in PennyLane."""
+
+from .conditionals import wires_in, wires_eq, op_in, op_eq, partial_wires