Add new transpiler exception class for too many qubits (#11241)

* Add new transpiler exception class for too many qubits

This commit adds a new exception class for when the transpiler is
given a circuit too many qubits for a given backend. Previously the
generic TranspilerError was raised for this, but it made it difficult
for downstream users to catch as it wasn't easy to differentiate this
error condition from other TranspilerError exceptions. There isn't any
backwards compatibility issues with this because the new
CircuitToWideForTarget class is a subclass of TranspilerError so any of
the previous catches for TranspilerError will still catch this.

* Fix typo in class name

* Make test check more specific exception type

* Replace :class: with :exc: in release note

qiskit/compiler/transpiler.py

@@ -28,7 +28,7 @@
 from qiskit.pulse import Schedule, InstructionScheduleMap
 from qiskit.transpiler import Layout, CouplingMap, PropertySet
 from qiskit.transpiler.basepasses import BasePass
-from qiskit.transpiler.exceptions import TranspilerError
+from qiskit.transpiler.exceptions import TranspilerError, CircuitTooWideForTarget
 from qiskit.transpiler.instruction_durations import InstructionDurations, InstructionDurationsType
 from qiskit.transpiler.passes.synthesis.high_level_synthesis import HLSConfig
 from qiskit.transpiler.preset_passmanagers import generate_preset_pass_manager
@@ -455,7 +455,7 @@ def _check_circuits_coupling_map(circuits, cmap, backend):
         # If coupling_map is not None or num_qubits == 1
         num_qubits = len(circuit.qubits)
         if max_qubits is not None and (num_qubits > max_qubits):
-            raise TranspilerError(
+            raise CircuitTooWideForTarget(
                 f"Number of qubits ({num_qubits}) in {circuit.name} "
                 f"is greater than maximum ({max_qubits}) in the coupling_map"
             )

qiskit/transpiler/__init__.py

@@ -1251,6 +1251,8 @@
 .. autoexception:: TranspilerAccessError
 .. autoexception:: CouplingError
 .. autoexception:: LayoutError
+.. autoexception:: CircuitTooWideForTarget
+
 """
 
 # For backward compatibility
@@ -1263,7 +1265,13 @@
 from .passmanager import PassManager, StagedPassManager
 from .passmanager_config import PassManagerConfig
 from .propertyset import PropertySet  # pylint: disable=no-name-in-module
-from .exceptions import TranspilerError, TranspilerAccessError, CouplingError, LayoutError
+from .exceptions import (
+    TranspilerError,
+    TranspilerAccessError,
+    CouplingError,
+    LayoutError,
+    CircuitTooWideForTarget,
+)
 from .fencedobjs import FencedDAGCircuit, FencedPropertySet
 from .basepasses import AnalysisPass, TransformationPass
 from .coupling import CouplingMap

qiskit/transpiler/exceptions.py

@@ -49,3 +49,7 @@ def __init__(self, *msg):
     def __str__(self):
         """Return the message."""
         return repr(self.msg)
+
+
+class CircuitTooWideForTarget(TranspilerError):
+    """Error raised if the circuit is too wide for the target."""

releasenotes/notes/new-exception-too-wide-3231c1df15952445.yaml

@@ -0,0 +1,9 @@
+---
+features:
+  - |
+    Added a new exception class :exc:`.CircuitToWideForTarget` which
+    subclasses :exc:`.TranspilerError`. It's used in places where a
+    :exc:`.TranspilerError` was previously raised when the error was that
+    the number of circuit qubits was larger than the target backend's qubits.
+    The new class enables more differentiating between this error condition and
+    other :exc:`.TranspilerError`\s.

test/python/compiler/test_transpiler.py

@@ -87,7 +87,7 @@
 from qiskit.test import QiskitTestCase, slow_test
 from qiskit.tools import parallel
 from qiskit.transpiler import CouplingMap, Layout, PassManager, TransformationPass
-from qiskit.transpiler.exceptions import TranspilerError
+from qiskit.transpiler.exceptions import TranspilerError, CircuitTooWideForTarget
 from qiskit.transpiler.passes import BarrierBeforeFinalMeasurements, GateDirection, VF2PostLayout
 from qiskit.transpiler.passmanager_config import PassManagerConfig
 from qiskit.transpiler.preset_passmanagers import generate_preset_pass_manager, level_0_pass_manager
@@ -987,7 +987,7 @@ def test_check_circuit_width(self):
 
         qc = QuantumCircuit(15, 15)
 
-        with self.assertRaises(TranspilerError):
+        with self.assertRaises(CircuitTooWideForTarget):
             transpile(qc, coupling_map=cmap)
 
     @data(0, 1, 2, 3)