Adjust docstring

qiskit/circuit/__init__.py

@@ -1060,9 +1060,10 @@ def __array__(self, dtype=None, copy=None):
 Pauli twirling is a quantum error suppression technique that uses randomization to shape coherent
 error into stochastic errors by combining the results from many random, but logically equivalent
 circuits, together. Qiskit provides a function to apply Pauli twirling to a given circuit for
-standard two qubit gates.
+standard two qubit gates. For more details you can refer to the documentation of the function
+below:
 
-.. autofunction:: qiskit.circuit.twirl_circuit
+.. autofunction:: qiskit.circuit.pauli_twirl_2q_gates
 
 
 Exceptions
@@ -1309,4 +1310,4 @@ def __array__(self, dtype=None, copy=None):
 )
 
 from .annotated_operation import AnnotatedOperation, InverseModifier, ControlModifier, PowerModifier
-from .twirling import twirl_circuit
+from .twirling import pauli_twirl_2q_gates

qiskit/circuit/twirling.py

@@ -33,15 +33,28 @@
 }
 
 
-def twirl_circuit(
+def pauli_twirl_2q_gates(
     circuit: QuantumCircuit,
     twirling_gate: None | str | Gate | list[str] | list[Gate] = None,
     seed: int | None = None,
     num_twirls: int | None = None,
     target: Target | None = None,
 ) -> QuantumCircuit | list[QuantumCircuit]:
-    """Create a copy of a given circuit with Pauli twirling applied around a specified two qubit
-    gate.
+    """Create copies of a given circuit with Pauli twirling applied around specified two qubit
+    gates.
+
+    If you're running this function with the intent to twirl a circuit to run on hardware this
+    may not be the most efficient way to perform twirling. Especially if the hardware vendor
+    has implemented the :mod:`.primitives` execution interface with :class:`.SamplerV2` and
+    :class:`.EstimatorV2` this most likely is not the best way to apply twirling to your
+    circuit and you'll want to refer to the implementation of :class:`.SamplerV2` and/or
+    :class:`.EstimatorV2` for the specified hardware vendor.
+
+    If the intent of this function is to be run after :func:`.transpile` or
+    :meth:`.PassManager.run` the optional ``target`` argument can be used
+    so that the inserted 1 qubit Pauli gates are synthesized to be
+    compatible with the given :class:`.Target` so the output circuit(s) are
+    still compatible.
 
     Args:
         circuit: The circuit to twirl
@@ -53,9 +66,9 @@ def twirl_circuit(
             have a matrix defined from its :class:`~.Gate.to_matrix` method for the gate to potentially
             be twirled. If a valid twirling configuration can't be computed that particular gate will
             be silently ignored and not twirled.
-        seed: An integer seed for the random number generator used internally.
+        seed: An integer seed for the random number generator used internally by this function.
             If specified this must be between 0 and 18,446,744,073,709,551,615.
-        num_twirls: The number of twirling circuits to build. This defaults to None and will return
+        num_twirls: The number of twirling circuits to build. This defaults to ``None`` and will return
             a single circuit. If it is an integer a list of circuits with `num_twirls` circuits
             will be returned.
         target: If specified an :class:`.Target` instance to use for running single qubit decomposition