qiskit 2.0.3__cp39-abi3-macosx_11_0_arm64.whl → 2.1.0__cp39-abi3-macosx_11_0_arm64.whl

qiskit/transpiler/passes/synthesis/plugin.py

@@ -361,6 +361,10 @@ Unitary Synthesis Plugins
    :no-inherited-members:
    :no-special-members:
 
+.. automodule:: qiskit.transpiler.passes.synthesis.clifford_unitary_synth_plugin
+   :no-inherited-members:
+   :no-special-members:
+
 
 High Level Synthesis
 --------------------

qiskit/transpiler/passes/synthesis/solovay_kitaev_synthesis.py

@@ -29,9 +29,6 @@ from qiskit.converters import circuit_to_dag
 from qiskit.circuit.gate import Gate
 from qiskit.dagcircuit import DAGCircuit
 from qiskit.synthesis.discrete_basis.solovay_kitaev import SolovayKitaevDecomposition
-from qiskit.synthesis.discrete_basis.generate_basis_approximations import (
-    generate_basic_approximations,
-)
 from qiskit.transpiler.basepasses import TransformationPass
 from qiskit.transpiler.passes.utils.control_flow import trivial_recurse
 
@@ -137,23 +134,35 @@ class SolovayKitaev(TransformationPass):
 
     def __init__(
         self,
-        recursion_degree: int = 3,
+        recursion_degree: int = 5,
         basic_approximations: str | dict[str, np.ndarray] | None = None,
+        *,
+        basis_gates: list[str | Gate] | None = None,
+        depth: int = 12,
     ) -> None:
-        """
+        r"""
         Args:
             recursion_degree: The recursion depth for the Solovay-Kitaev algorithm.
                 A larger recursion depth increases the accuracy and length of the
                 decomposition.
             basic_approximations: The basic approximations for the finding the best discrete
-                decomposition at the root of the recursion. If a string, it specifies the ``.npy``
+                decomposition at the root of the recursion. If a string, it specifies the
                 file to load the approximations from. If a dictionary, it contains
-                ``{label: SO(3)-matrix}`` pairs. If None, a default based on the H, T and Tdg gates
-                up to combinations of depth 10 is generated.
+                ``{label: SO(3)-matrix}`` pairs. If ``None``, a default based on the :math:`H`,
+                :math:`T` and :math:`T^\dagger` gates up to depth 16 is generated.
+                Note that if ``basic_approximations`` is passed, ``basis_gates`` and
+                ``depth`` cannot be set.
+            basis_gates: The basis gates used to build the net of basic approximations.
+                Defaults to ``["h", "t", "tdg"]``. This argument cannot be set if
+                ``basic_approximations`` is provided.
+            depth: The maximal gate depth used in basic approximations. This argument cannot be
+                set if ``basic_approximations`` is provided.
         """
         super().__init__()
         self.recursion_degree = recursion_degree
-        self._sk = SolovayKitaevDecomposition(basic_approximations)
+        self._sk = SolovayKitaevDecomposition(
+            basic_approximations, basis_gates=basis_gates, depth=depth
+        )
 
     @trivial_recurse
     def run(self, dag: DAGCircuit) -> DAGCircuit:
@@ -169,7 +178,6 @@ class SolovayKitaev(TransformationPass):
             TranspilerError: if a gates does not have to_matrix
         """
         for node in dag.op_nodes():
-
             # ignore operations on which the algorithm cannot run
             if (
                 (node.op.num_qubits != 1)
@@ -182,11 +190,9 @@ class SolovayKitaev(TransformationPass):
             # we know it will generate a valid SU(2) matrix
             check_input = not isinstance(node.op, Gate)
 
-            matrix = node.op.to_matrix()
-
             # call solovay kitaev
             approximation = self._sk.run(
-                matrix, self.recursion_degree, return_dag=True, check_input=check_input
+                node.op, self.recursion_degree, return_dag=True, check_input=check_input
             )
 
             # convert to a dag and replace the gate by the approximation
@@ -221,12 +227,12 @@ class SolovayKitaevSynthesis(UnitarySynthesisPlugin):
 
     depth (int):
         The gate-depth of the basic approximations. All possible, unique combinations of the
-        basis gates up to length ``depth`` are considered. If None, defaults to 10.
+        basis gates up to length ``depth`` are considered. If None, defaults to 12.
         If ``basic_approximations`` is not None, ``depth`` is required to correspond to the
         depth that was used to generate it.
 
     recursion_degree (int):
-        The number of times the decomposition is recursively improved. If None, defaults to 3.
+        The number of times the decomposition is recursively improved. If None, defaults to 5.
     """
 
     # Generating basic approximations of single-qubit gates is computationally expensive.
@@ -292,10 +298,10 @@ class SolovayKitaevSynthesis(UnitarySynthesisPlugin):
         """Run the SolovayKitaevSynthesis synthesis plugin on the given unitary."""
 
         config = options.get("config") or {}
-        basis_gates = options.get("basis_gates", ["h", "t", "tdg"])
-        depth = config.get("depth", 10)
+        basis_gates = options.get("basis_gates", None)
+        depth = config.get("depth", 12)
         basic_approximations = config.get("basic_approximations", None)
-        recursion_degree = config.get("recursion_degree", 3)
+        recursion_degree = config.get("recursion_degree", 5)
 
         # Check if we didn't yet construct the Solovay-Kitaev instance (which contains the basic
         # approximations) or if the basic approximations need need to be recomputed.
@@ -303,11 +309,10 @@ class SolovayKitaevSynthesis(UnitarySynthesisPlugin):
             (basis_gates != SolovayKitaevSynthesis._basis_gates)
             or (depth != SolovayKitaevSynthesis._depth)
         ):
-            if basic_approximations is None:
-                basic_approximations = generate_basic_approximations(basis_gates, depth)
-
             SolovayKitaevSynthesis._basis_gates = basis_gates
             SolovayKitaevSynthesis._depth = depth
-            SolovayKitaevSynthesis._sk = SolovayKitaevDecomposition(basic_approximations)
+            SolovayKitaevSynthesis._sk = SolovayKitaevDecomposition(
+                basic_approximations, basis_gates=basis_gates, depth=depth
+            )
         approximate_circuit = SolovayKitaevSynthesis._sk.run(unitary, recursion_degree)
         return circuit_to_dag(approximate_circuit)

qiskit/transpiler/passmanager_config.py

@@ -95,6 +95,9 @@ class PassManagerConfig:
         self.target = target
         self.hls_config = hls_config
         self.qubits_initially_zero = qubits_initially_zero
+        # Stores whether the basis gates are Clifford+T,
+        # in which case we use stage manager plugins adapted to Clifford+T.
+        self._is_clifford_t = False
 
     @classmethod
     def from_backend(cls, backend, _skip_target=False, **pass_manager_options):

qiskit/transpiler/preset_passmanagers/builtin_plugins.py

@@ -14,6 +14,7 @@
 
 import os
 
+from qiskit.transpiler.passes.layout.vf2_post_layout import VF2PostLayout
 from qiskit.transpiler.passes.optimization.split_2q_unitaries import Split2QUnitaries
 from qiskit.transpiler.passmanager import PassManager
 from qiskit.transpiler.exceptions import TranspilerError
@@ -30,6 +31,8 @@ from qiskit.transpiler.passes import CheckMap
 from qiskit.transpiler.passes import BarrierBeforeFinalMeasurements
 from qiskit.transpiler.passes import ElidePermutations
 from qiskit.transpiler.passes import RemoveDiagonalGatesBeforeMeasure
+from qiskit.transpiler.passes import OptimizeCliffordT
+from qiskit.transpiler.passes import BasisTranslator
 from qiskit.transpiler.preset_passmanagers import common
 from qiskit.transpiler.preset_passmanagers.plugin import (
     PassManagerStagePlugin,
@@ -66,6 +69,7 @@ from qiskit.circuit.library.standard_gates import (
     SXGate,
     SXdgGate,
 )
+from qiskit.circuit.equivalence_library import SessionEquivalenceLibrary as sel
 from qiskit.utils import default_num_processes
 from qiskit import user_config
 
@@ -86,6 +90,7 @@ class DefaultInitPassManager(PassManagerStagePlugin):
     """Plugin class for default init stage."""
 
     def pass_manager(self, pass_manager_config, optimization_level=None) -> PassManager:
+
         if optimization_level == 0:
             init = None
             if (
@@ -186,7 +191,12 @@ class DefaultInitPassManager(PassManagerStagePlugin):
                 ]
             )
             init.append(CommutativeCancellation())
-            init.append(ConsolidateBlocks())
+
+            # We do not want to consolidate blocks for a Clifford+T basis set,
+            # since this involves resynthesizing 2-qubit unitaries.
+            if not pass_manager_config._is_clifford_t:
+                init.append(ConsolidateBlocks())
+
             # If approximation degree is None that indicates a request to approximate up to the
             # error rates in the target. However, in the init stage we don't yet know the target
             # qubits being used to figure out the fidelity so just use the default fidelity parameter
@@ -215,6 +225,7 @@ class DefaultTranslationPassManager(PassManagerStagePlugin):
         # future if we want to change the default method to do more context-aware switching, or to
         # start transitioning the default method without breaking the semantics of the default
         # string referring to the `BasisTranslator`.
+
         return BasisTranslatorPassManager().pass_manager(pass_manager_config, optimization_level)
 
 
@@ -222,10 +233,14 @@ class BasisTranslatorPassManager(PassManagerStagePlugin):
     """Plugin class for translation stage with :class:`~.BasisTranslator`"""
 
     def pass_manager(self, pass_manager_config, optimization_level=None) -> PassManager:
+        if pass_manager_config._is_clifford_t:
+            method = "clifford_t"
+        else:
+            method = "translator"
         return common.generate_translation_passmanager(
             pass_manager_config.target,
             basis_gates=pass_manager_config.basis_gates,
-            method="translator",
+            method=method,
             approximation_degree=pass_manager_config.approximation_degree,
             coupling_map=pass_manager_config.coupling_map,
             unitary_synthesis_method=pass_manager_config.unitary_synthesis_method,
@@ -496,6 +511,13 @@ class OptimizationPassManager(PassManagerStagePlugin):
 
     def pass_manager(self, pass_manager_config, optimization_level=None) -> PassManager:
         """Build pass manager for optimization stage."""
+
+        # Use the dedicated plugin for the Clifford+T basis when appropriate.
+        if pass_manager_config._is_clifford_t:
+            return CliffordTOptimizationPassManager().pass_manager(
+                pass_manager_config, optimization_level
+            )
+
         # Obtain the translation method required for this pass to work
         translation_method = pass_manager_config.translation_method or "default"
         optimization = PassManager()
@@ -646,6 +668,23 @@ class OptimizationPassManager(PassManagerStagePlugin):
                 else _opt + _unroll_if_out_of_basis + _depth_check + _size_check
             )
             optimization.append(DoWhileController(opt_loop, do_while=_opt_control))
+
+            if optimization_level == 3 and pass_manager_config.coupling_map:
+                vf2_call_limit, vf2_max_trials = common.get_vf2_limits(
+                    optimization_level,
+                    pass_manager_config.layout_method,
+                    pass_manager_config.initial_layout,
+                )
+                optimization.append(
+                    VF2PostLayout(
+                        target=pass_manager_config.target,
+                        seed=-1,
+                        call_limit=vf2_call_limit,
+                        max_trials=vf2_max_trials,
+                        strict_direction=True,
+                    )
+                )
+
             return optimization
         else:
             return None
@@ -736,13 +775,18 @@ class DefaultLayoutPassManager(PassManagerStagePlugin):
         layout = PassManager()
         layout.append(_given_layout)
         if optimization_level == 0:
-            layout.append(
-                ConditionalController(
-                    TrivialLayout(coupling_map), condition=_choose_layout_condition
+            if coupling_map is not None:
+                layout.append(
+                    ConditionalController(
+                        TrivialLayout(coupling_map), condition=_choose_layout_condition
+                    )
                 )
-            )
             layout += common.generate_embed_passmanager(coupling_map)
             return layout
+
+        if coupling_map is None:
+            # There's nothing to lay out onto.  We only need to embed the initial layout, if given.
+            pass
         elif optimization_level == 1:
             layout.append(
                 ConditionalController(
@@ -870,9 +914,12 @@ class TrivialLayoutPassManager(PassManagerStagePlugin):
 
         layout = PassManager()
         layout.append(_given_layout)
-        layout.append(
-            ConditionalController(TrivialLayout(coupling_map), condition=_choose_layout_condition)
-        )
+        if coupling_map is not None:
+            layout.append(
+                ConditionalController(
+                    TrivialLayout(coupling_map), condition=_choose_layout_condition
+                )
+            )
         layout += common.generate_embed_passmanager(coupling_map)
         return layout
 
@@ -893,15 +940,16 @@ class DenseLayoutPassManager(PassManagerStagePlugin):
 
         layout = PassManager()
         layout.append(_given_layout)
-        layout.append(
-            ConditionalController(
-                DenseLayout(
-                    coupling_map=pass_manager_config.coupling_map,
-                    target=pass_manager_config.target,
-                ),
-                condition=_choose_layout_condition,
+        if coupling_map is not None:
+            layout.append(
+                ConditionalController(
+                    DenseLayout(
+                        coupling_map=pass_manager_config.coupling_map,
+                        target=pass_manager_config.target,
+                    ),
+                    condition=_choose_layout_condition,
+                )
             )
-        )
         layout += common.generate_embed_passmanager(coupling_map)
         return layout
 
@@ -925,7 +973,9 @@ class SabreLayoutPassManager(PassManagerStagePlugin):
 
         layout = PassManager()
         layout.append(_given_layout)
-        if optimization_level == 0:
+        if coupling_map is None:
+            layout_pass = None
+        elif optimization_level == 0:
             trial_count = _get_trial_count(5)
 
             layout_pass = SabreLayout(
@@ -971,17 +1021,18 @@ class SabreLayoutPassManager(PassManagerStagePlugin):
             )
         else:
             raise TranspilerError(f"Invalid optimization level: {optimization_level}")
-        layout.append(
-            ConditionalController(
-                [
-                    BarrierBeforeFinalMeasurements(
-                        "qiskit.transpiler.internal.routing.protection.barrier"
-                    ),
-                    layout_pass,
-                ],
-                condition=_choose_layout_condition,
+        if layout_pass is not None:
+            layout.append(
+                ConditionalController(
+                    [
+                        BarrierBeforeFinalMeasurements(
+                            "qiskit.transpiler.internal.routing.protection.barrier"
+                        ),
+                        layout_pass,
+                    ],
+                    condition=_choose_layout_condition,
+                )
             )
-        )
         embed = common.generate_embed_passmanager(coupling_map)
         layout.append(ConditionalController(embed.to_flow_controller(), condition=_swap_mapped))
         return layout
@@ -991,3 +1042,73 @@ def _get_trial_count(default_trials=5):
     if CONFIG.get("sabre_all_threads", None) or os.getenv("QISKIT_SABRE_ALL_THREADS"):
         return max(default_num_processes(), default_trials)
     return default_trials
+
+
+class CliffordTOptimizationPassManager(PassManagerStagePlugin):
+    """Plugin class for optimization stage"""
+
+    def pass_manager(self, pass_manager_config, optimization_level=None) -> PassManager:
+        """Build pass manager for optimization stage."""
+
+        # Obtain the translation method required for this pass to work
+        optimization = PassManager()
+        if optimization_level != 0:
+            _depth_check = [Depth(recurse=True), FixedPoint("depth")]
+            _size_check = [Size(recurse=True), FixedPoint("size")]
+
+            def _opt_control(property_set):
+                return (not property_set["depth_fixed_point"]) or (
+                    not property_set["size_fixed_point"]
+                )
+
+            if optimization_level == 1:
+                _opt = [
+                    InverseCancellation(
+                        [
+                            CXGate(),
+                            ECRGate(),
+                            CZGate(),
+                            CYGate(),
+                            XGate(),
+                            YGate(),
+                            ZGate(),
+                            HGate(),
+                            SwapGate(),
+                            (TGate(), TdgGate()),
+                            (SGate(), SdgGate()),
+                            (SXGate(), SXdgGate()),
+                        ]
+                    ),
+                    ContractIdleWiresInControlFlow(),
+                ]
+            elif optimization_level in [2, 3]:
+                # The optimization loop runs OptimizeCliffordT + CommutativeCancellation
+                # until fixpoint.
+                _opt = [
+                    RemoveIdentityEquivalent(
+                        approximation_degree=pass_manager_config.approximation_degree,
+                        target=pass_manager_config.target,
+                    ),
+                    OptimizeCliffordT(),
+                    CommutativeCancellation(target=pass_manager_config.target),
+                    ContractIdleWiresInControlFlow(),
+                ]
+
+            else:
+                raise TranspilerError(f"Invalid optimization_level: {optimization_level}")
+
+            # Build nested flow controllers
+            optimization.append(_depth_check + _size_check)
+
+            opt_loop = _opt + _depth_check + _size_check
+            optimization.append(DoWhileController(opt_loop, do_while=_opt_control))
+            # We need to run BasisTranslator because OptimizeCliffordT does not consider the basis set.
+            if optimization_level in [2, 3]:
+                optimization.append(
+                    BasisTranslator(
+                        sel, pass_manager_config.basis_gates, pass_manager_config.target
+                    )
+                )
+            return optimization
+        else:
+            return None

qiskit/transpiler/preset_passmanagers/common.py

@@ -51,6 +51,7 @@ from qiskit.transpiler.passes.layout.vf2_post_layout import VF2PostLayoutStopRea
 from qiskit.transpiler.exceptions import TranspilerError
 from qiskit.transpiler.layout import Layout
 from qiskit.utils import deprecate_func
+from qiskit.quantum_info.operators.symplectic.clifford_circuits import _CLIFFORD_GATE_NAMES
 
 
 _ControlFlowState = collections.namedtuple("_ControlFlowState", ("working", "not_working"))
@@ -485,6 +486,74 @@ def generate_translation_passmanager(
             translator,
         ]
         fix_1q = [translator]
+    elif method == "clifford_t":
+        # The list of extended basis gates consists of the specified Clifford+T basis gates and
+        # additionally the 1q-gate "u".
+        # We set target=None to make sure extended_basis_gates is not overwritten by the target.
+        extended_basis_gates = list(basis_gates) + ["u"]
+
+        unroll = [
+            # Use the UnitarySynthesis pass to unroll 1-qubit and 2-qubit gates named "unitary" into
+            # extended_basis_gates.
+            UnitarySynthesis(
+                basis_gates=extended_basis_gates,
+                approximation_degree=approximation_degree,
+                coupling_map=coupling_map,
+                plugin_config=unitary_synthesis_plugin_config,
+                method=unitary_synthesis_method,
+                target=None,
+            ),
+            # Use the HighLevelSynthesis pass to unroll all the remaining 1q and 2q custom
+            # gates into extended_basis_gates + the gates in the equivalence library.
+            # We set target=None to make sure extended_basis_gates is not overwritten by the target.
+            HighLevelSynthesis(
+                hls_config=hls_config,
+                coupling_map=coupling_map,
+                target=None,
+                use_qubit_indices=True,
+                equivalence_library=sel,
+                basis_gates=extended_basis_gates,
+                qubits_initially_zero=qubits_initially_zero,
+            ),
+            # Use the BasisTranslator pass to translate all the gates into extended_basis_gates.
+            # In other words, this translates the gates in the equivalence library that are not
+            # in extended_basis_gates to gates in extended_basis_gates only.
+            # Note that we do not want to make any assumptions on which Clifford gates are present
+            # in basis_gates. The BasisTranslator will do the conversion if possible (and provide
+            # a helpful error message otherwise).
+            BasisTranslator(sel, extended_basis_gates, None),
+            # The next step is to resynthesize blocks of consecutive 1q-gates into ["h", "t", "tdg"].
+            # Use Collect1qRuns and ConsolidateBlocks passes to replace such blocks by 1q "unitary"
+            # gates.
+            Collect1qRuns(),
+            ConsolidateBlocks(
+                basis_gates=None,
+                target=None,
+                approximation_degree=approximation_degree,
+                force_consolidate=True,
+            ),
+            # We use the "clifford" unitary synthesis plugin to replace single-qubit
+            # unitary gates that can be represented as Cliffords by Clifford gates.
+            UnitarySynthesis(method="clifford", plugin_config={"max_qubits": 1}),
+            # We use the Solovay-Kitaev decomposition via the plugin mechanism for "sk"
+            # UnitarySynthesisPlugin.
+            UnitarySynthesis(
+                basis_gates=["h", "t", "tdg"],
+                approximation_degree=approximation_degree,
+                coupling_map=coupling_map,
+                plugin_config=unitary_synthesis_plugin_config,
+                method="sk",
+                min_qubits=1,
+                target=None,
+            ),
+            # Finally, we use BasisTranslator to translate ["h", "t", "tdg"] to the actually
+            # specified set of basis gates.
+            BasisTranslator(sel, basis_gates, target),
+        ]
+        # We use the BasisTranslator pass to translate any 1q-gates added by GateDirection
+        # into basis_gates.
+        translator = BasisTranslator(sel, basis_gates, target)
+        fix_1q = [translator]
     elif method == "synthesis":
         unroll = [
             # # Use unitary synthesis for basis aware decomposition of
@@ -670,3 +739,35 @@ def get_vf2_limits(
                 250000,  # Limits layout scoring to < 60 sec on ~400 qubit devices
             )
     return limits
+
+
+# Clifford+T basis, consisting of Clifford+T gate names + additional instruction names
+# that are a part of every basis
+_CLIFFORD_T_BASIS = set(_CLIFFORD_GATE_NAMES).union(
+    {"t", "tdg", "delay", "barrier", "reset", "measure"}.union(CONTROL_FLOW_OP_NAMES)
+)
+
+
+def is_clifford_t_basis(basis_gates=None, target=None) -> bool:
+    """
+    Checks whether the given basis set can be considered as Clifford+T.
+
+    For this we require that:
+    1. The set only contains Clifford+T gates,
+    2. The set contains either T or Tdg gate or both.
+
+    In particular, these conditions guarantee that the empty basis set
+    is not considered as Clifford+T.
+    """
+
+    if target is not None:
+        basis = set(target.operation_names)
+    elif basis_gates is not None:
+        basis = set(basis_gates)
+    else:
+        basis = set()
+
+    if (basis_gates is None) or (("t" not in basis_gates) and ("tdg" not in basis_gates)):
+        return False
+
+    return basis.issubset(_CLIFFORD_T_BASIS)

qiskit/transpiler/preset_passmanagers/generate_preset_pass_manager.py

@@ -25,6 +25,7 @@ from qiskit.transpiler.exceptions import TranspilerError
 from qiskit.transpiler.instruction_durations import InstructionDurations
 from qiskit.transpiler.layout import Layout
 from qiskit.transpiler.passmanager_config import PassManagerConfig
+from qiskit.transpiler.preset_passmanagers.common import is_clifford_t_basis
 from qiskit.transpiler.target import Target, _FakeTarget
 from qiskit.transpiler.timing_constraints import TimingConstraints
 
@@ -302,6 +303,11 @@ def generate_preset_pass_manager(
         pm_config = PassManagerConfig.from_backend(backend, **pm_options)
     else:
         pm_config = PassManagerConfig(**pm_options)
+
+    pm_config._is_clifford_t = is_clifford_t_basis(
+        basis_gates=pm_config.basis_gates, target=pm_config.target
+    )
+
     if optimization_level == 0:
         pm = level_0_pass_manager(pm_config)
     elif optimization_level == 1:

qiskit/transpiler/preset_passmanagers/level3.py

@@ -36,7 +36,8 @@ def level_3_pass_manager(pass_manager_config: PassManagerConfig) -> StagedPassMa
     The pass manager then transforms the circuit to match the coupling constraints.
     It is then unrolled to the basis, and any flipped cx directions are fixed.
     Finally, optimizations in the form of commutative gate cancellation, resynthesis
-    of two-qubit unitary blocks, and redundant reset removal are performed.
+    of two-qubit unitary blocks, redundant reset removal and final layout improvements are
+    performed.
 
     Args:
         pass_manager_config: configuration of the pass manager.
@@ -55,7 +56,6 @@ def level_3_pass_manager(pass_manager_config: PassManagerConfig) -> StagedPassMa
     layout_method = pass_manager_config.layout_method or "default"
     routing_method = pass_manager_config.routing_method or "default"
     translation_method = pass_manager_config.translation_method or "default"
-    scheduling_method = pass_manager_config.scheduling_method
     optimization_method = pass_manager_config.optimization_method or "default"
     scheduling_method = pass_manager_config.scheduling_method or "default"
     target = pass_manager_config.target

qiskit/transpiler/target.py

@@ -159,6 +159,13 @@ class Target(BaseTarget):
     angle :class:`~qiskit.circuit.library.RXGate` while ``rx`` will get the
     parameterized :class:`~qiskit.circuit.library.RXGate`.
 
+    This class can be queried via the mapping protocol, using the
+    instruction's name as a key. You can modify any property for an
+    instruction via the :meth:`.update_instruction_properties` method.
+    Modification via the mapping protocol or mutating the attributes of
+    a :class:`.InstructionProperties` object is **not** supported and
+    doing so will invalidate the internal state of the object.
+
     .. note::
 
         This class assumes that qubit indices start at 0 and are a contiguous
@@ -167,7 +174,7 @@ class Target(BaseTarget):
 
     .. note::
 
-        This class only supports additions of gates, qargs, and qubits.
+        This class only supports additions of gates, qargs, and properties.
         If you need to remove one of these the best option is to iterate over
         an existing object and create a new subset (or use one of the methods
         to do this). The object internally caches different views and these
@@ -373,7 +380,13 @@ class Target(BaseTarget):
         self._instruction_schedule_map = None
 
     def update_instruction_properties(self, instruction, qargs, properties):
-        """Update the property object for an instruction qarg pair already in the Target
+        """Update the property object for an instruction qarg pair already in the Target.
+
+        For ease of access, a user is able to obtain the mapping between an instruction's
+        applicable qargs and its instruction properties via the mapping protocol (using ``__getitem__``),
+        with the instruction's name as the key. This method is the only way to
+        modify/update the properties of an instruction in the ``Target``. Usage of the mapping protocol
+        for modifications is not supported.
 
         Args:
             instruction (str): The instruction name to update

qiskit/utils/optionals.py

@@ -173,16 +173,17 @@ External Python Libraries
 .. py:data:: HAS_SYMENGINE
 
     `Symengine <https://github.com/symengine/symengine>`__ is a fast C++ backend for the
-    symbolic-manipulation library `Sympy <https://www.sympy.org/en/index.html>`__.  Qiskit uses
-    special methods from Symengine to accelerate its handling of
-    :class:`~.circuit.Parameter`\\ s if available.
+    symbolic-manipulation library `Sympy <https://www.sympy.org/en/index.html>`__.  This
+    dependency is used to load legacy QPY formats, where this package was used to handle
+    :class:`~.circuit.Parameter`\\ s.
 
 .. py:data:: HAS_SYMPY
 
     `SymPy <https://www.sympy.org/en/index.html>`__ is Python library for symbolic mathematics.
-    Sympy was historically used for the implementation of the :class:`.ParameterExpression`
+    ``SymPy`` was historically used for the implementation of the :class:`.ParameterExpression`
     class but isn't any longer. However it is needed for some legacy functionality that uses
-    :meth:`.ParameterExpression.sympify`. It is also used in some visualization functions.
+    :meth:`.ParameterExpression.sympify`. It is also used in some visualization functions
+    and template matching.
 
 .. py:data:: HAS_TESTTOOLS
 

qiskit/visualization/circuit/_utils.py

@@ -19,6 +19,7 @@ from warnings import warn
 import numpy as np
 
 from qiskit.circuit import (
+    BoxOp,
     ClassicalRegister,
     Clbit,
     ControlFlowOp,
@@ -499,9 +500,10 @@ def _get_gate_span(qubits, node):
         if index > max_index:
             max_index = index
 
-    # Because of wrapping boxes for mpl control flow ops, this
-    # type of op must be the only op in the layer
-    if isinstance(node.op, ControlFlowOp):
+    if isinstance(node.op, ControlFlowOp) and not isinstance(node.op, BoxOp):
+        # Because of wrapping boxes for mpl control flow ops, this
+        # type of op must be the only op in the layer
+        # BoxOps are excepted because they have one block executed unconditionally
         span = qubits
     elif node.cargs or getattr(node, "condition", None):
         span = qubits[min_index : len(qubits)]