add documentation about instruction duration (Qiskit#13592)

* add docuemntation about instruction duration

* more docs and some spelling

* Apply suggestions from code review

Co-authored-by: Elena Peña Tapia <[email protected]>

* Update qiskit/circuit/instruction.py

* Fix black

* Fix lint

---------

Co-authored-by: Elena Peña Tapia <[email protected]>
Co-authored-by: Elena Peña Tapia <[email protected]>

Author: 1ucian0

qiskit/circuit/instruction.py

@@ -63,14 +63,20 @@ class Instruction(Operation):
     def __init__(self, name, num_qubits, num_clbits, params, duration=None, unit="dt", label=None):
         """Create a new instruction.
 
+        .. deprecated:: 1.3
+           The parameters ``duration`` and ``unit`` are deprecated since
+           Qiskit 1.3, and they will be removed in 2.0 or later.
+           An instruction's duration is defined in a backend's Target object.
+
         Args:
             name (str): instruction name
             num_qubits (int): instruction's qubit width
             num_clbits (int): instruction's clbit width
             params (list[int|float|complex|str|ndarray|list|ParameterExpression]):
                 list of parameters
-            duration (int or float): instruction's duration. it must be integer if ``unit`` is 'dt'
-            unit (str): time unit of duration
+            duration (int|float): (DEPRECATED) instruction's duration. it must be
+                an integer if ``unit`` is ``'dt'``
+            unit (str): (DEPRECATED) time unit of duration
             label (str or None): An optional label for identifying the instruction.
 
         Raises:

qiskit/pulse/utils.py

@@ -51,7 +51,7 @@ def format_parameter_value(
         decimal: Number of digit to round returned value.
 
     Returns:
-        Value casted to non-parameter data type, when possible.
+        Value cast to non-parameter data type, when possible.
     """
     if isinstance(operand, ParameterExpression):
         try:

qiskit/visualization/timeline/core.py

@@ -142,6 +142,15 @@ def add_data(self, data: drawings.ElementaryData):
     def load_program(self, program: circuit.QuantumCircuit, target: Target | None = None):
         """Load quantum circuit and create drawing..
 
+        .. deprecated:: 1.3
+           Visualization of unscheduled circuits with the timeline drawer has been
+           deprecated in Qiskit 1.3.
+           This circuit should be transpiled with a scheduler, despite having instructions
+           with explicit durations.
+
+        .. deprecated:: 1.3
+           Targets with duration-less operations are going to error in Qiskit 2.0.
+
         Args:
             program: Scheduled circuit object to draw.
             target: The target the circuit is scheduled for. This contains backend information

qiskit/visualization/timeline/interface.py

@@ -52,6 +52,10 @@ def draw(
 ):
     r"""Generate visualization data for scheduled circuit programs.
 
+    .. deprecated:: 1.3
+       The ``target`` parameter needs to be specified in Qiskit 2.0 in order to get the
+       instruction durations.
+
     Args:
         program: Program to visualize. This program should be a `QuantumCircuit` which is
             transpiled with a scheduling_method, thus containing gate time information.