From b4bc559228c3898817978c3d8c3fc97372beecad Mon Sep 17 00:00:00 2001 From: Luciano Bello Date: Thu, 16 Mar 2023 15:56:55 +0100 Subject: [PATCH] Some doc formatting and link, mostly on quantumcircuit.py file (#9771) * some doc formating and link, mostly on quantumcircuit.py file * Update qiskit/circuit/quantumcircuit.py Co-authored-by: Julien Gacon * ident * more typos * more typos * another iteration * Bit and Register * notes on Register and Bit * Update qiskit/circuit/bit.py Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com> * Update qiskit/circuit/register.py Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com> --------- Co-authored-by: Julien Gacon Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com> Co-authored-by: Jake Lishman --- qiskit/algorithms/optimizers/qnspsa.py | 2 +- qiskit/circuit/__init__.py | 4 ++ qiskit/circuit/bit.py | 8 ++- qiskit/circuit/controlflow/for_loop.py | 2 +- qiskit/circuit/instruction.py | 7 ++- qiskit/circuit/instructionset.py | 8 +-- qiskit/circuit/quantumcircuit.py | 72 +++++++++++++------------- qiskit/circuit/register.py | 8 ++- 8 files changed, 63 insertions(+), 48 deletions(-) diff --git a/qiskit/algorithms/optimizers/qnspsa.py b/qiskit/algorithms/optimizers/qnspsa.py index 207c9f59bbf..baef9f3c7ac 100644 --- a/qiskit/algorithms/optimizers/qnspsa.py +++ b/qiskit/algorithms/optimizers/qnspsa.py @@ -277,7 +277,7 @@ def get_fidelity( F(\theta, \phi) = \big|\langle 0 | U^\dagger(\theta) U(\phi) |0\rangle \big|^2. The output of this function can be used as input for the ``fidelity`` to the - :class:~`qiskit.algorithms.optimizers.QNSPSA` optimizer. + :class:`~.QNSPSA` optimizer. Args: circuit: The circuit preparing the parameterized ansatz. diff --git a/qiskit/circuit/__init__.py b/qiskit/circuit/__init__.py index 7da3bf2d41e..bf51754a458 100644 --- a/qiskit/circuit/__init__.py +++ b/qiskit/circuit/__init__.py @@ -263,6 +263,8 @@ AncillaRegister AncillaQubit CircuitInstruction + Register + Bit Gates and Instructions ---------------------- @@ -328,6 +330,8 @@ from .parameterexpression import ParameterExpression from .quantumcircuitdata import CircuitInstruction from .equivalence import EquivalenceLibrary +from .bit import Bit +from .register import Register from . import library from .commutation_checker import CommutationChecker diff --git a/qiskit/circuit/bit.py b/qiskit/circuit/bit.py index 2577357e43b..9d8cdbd0af2 100644 --- a/qiskit/circuit/bit.py +++ b/qiskit/circuit/bit.py @@ -19,7 +19,13 @@ class Bit: - """Implement a generic bit.""" + """Implement a generic bit. + + .. note:: + This class should not be instantiated directly. This is just a superclass + for :class:`~.Clbit` and :class:`~.Qubit`. + + """ __slots__ = {"_register", "_index", "_hash", "_repr"} diff --git a/qiskit/circuit/controlflow/for_loop.py b/qiskit/circuit/controlflow/for_loop.py index 4a215db8ff0..5761dc7ab67 100644 --- a/qiskit/circuit/controlflow/for_loop.py +++ b/qiskit/circuit/controlflow/for_loop.py @@ -142,7 +142,7 @@ class ForLoopContext: from qiskit import QuantumCircuit qc = QuantumCircuit(2, 1) - with qc.for_loop(None, range(5)) as i: + with qc.for_loop(range(5)) as i: qc.rx(i * math.pi/4, 0) qc.cx(0, 1) qc.measure(0, 0) diff --git a/qiskit/circuit/instruction.py b/qiskit/circuit/instruction.py index c86a63ff01b..7623892a612 100644 --- a/qiskit/circuit/instruction.py +++ b/qiskit/circuit/instruction.py @@ -417,12 +417,11 @@ def copy(self, name=None): Copy of the instruction. Args: - name (str): name to be given to the copied circuit, - if None then the name stays the same. + name (str): name to be given to the copied circuit, if ``None`` then the name stays the same. Returns: - qiskit.circuit.Instruction: a copy of the current instruction, with the name - updated if it was provided + qiskit.circuit.Instruction: a copy of the current instruction, with the name updated if it + was provided """ cpy = self.__deepcopy__() diff --git a/qiskit/circuit/instructionset.py b/qiskit/circuit/instructionset.py index 10155460030..188b98fef8d 100644 --- a/qiskit/circuit/instructionset.py +++ b/qiskit/circuit/instructionset.py @@ -95,14 +95,14 @@ class InstructionSet: def __init__(self, circuit_cregs=None, *, resource_requester: Optional[Callable] = None): """New collection of instructions. - The context (qargs and cargs that each instruction is attached to) is also stored separately - for each instruction. + The context (``qargs`` and ``cargs`` that each instruction is attached to) is also stored + separately for each instruction. Args: - circuit_cregs (list[ClassicalRegister]): Optional. List of cregs of the + circuit_cregs (list[ClassicalRegister]): Optional. List of ``cregs`` of the circuit to which the instruction is added. Default: `None`. - .. deprecated:: qiskit-terra 0.19 + .. deprecated:: 0.19 The classical registers are insufficient to access all classical resources in a circuit, as there may be loose classical bits as well. It can also cause integer indices to be resolved incorrectly if any registers overlap. Instead, diff --git a/qiskit/circuit/quantumcircuit.py b/qiskit/circuit/quantumcircuit.py index f9760a56c6a..f75aef9db0b 100644 --- a/qiskit/circuit/quantumcircuit.py +++ b/qiskit/circuit/quantumcircuit.py @@ -130,11 +130,11 @@ class QuantumCircuit: A circuit is a list of instructions bound to some registers. Args: - regs (list(:class:`Register`) or list(``int``) or list(list(:class:`Bit`))): The + regs (list(:class:`~.Register`) or list(``int``) or list(list(:class:`~.Bit`))): The registers to be included in the circuit. - * If a list of :class:`Register` objects, represents the :class:`QuantumRegister` - and/or :class:`ClassicalRegister` objects to include in the circuit. + * If a list of :class:`~.Register` objects, represents the :class:`.QuantumRegister` + and/or :class:`.ClassicalRegister` objects to include in the circuit. For example: @@ -151,8 +151,8 @@ class QuantumCircuit: * ``QuantumCircuit(4) # A QuantumCircuit with 4 qubits`` * ``QuantumCircuit(4, 3) # A QuantumCircuit with 4 qubits and 3 classical bits`` - * If a list of python lists containing :class:`Bit` objects, a collection of - :class:`Bit` s to be added to the circuit. + * If a list of python lists containing :class:`.Bit` objects, a collection of + :class:`.Bit` s to be added to the circuit. name (str): the name of the quantum circuit. If not set, an @@ -1217,8 +1217,7 @@ def append( were actually added to the circuit. Raises: - CircuitError: if the operation passed is not an instance of - :class:`~.circuit..Instruction`. + CircuitError: if the operation passed is not an instance of :class:`~.circuit.Instruction` . """ if isinstance(instruction, CircuitInstruction): operation = instruction.operation @@ -1855,10 +1854,10 @@ def draw( Default is True, except for when ``output`` is set to ``"text"``. wire_order (list): Optional. A list of integers used to reorder the display of the bits. The list must have an entry for every bit with the bits - in the range 0 to (num_qubits + num_clbits). + in the range 0 to (``num_qubits`` + ``num_clbits``). Returns: - :class:`TextDrawing` or :class:`matplotlib.figure` or :class:`PIL.Image` or + :class:`.TextDrawing` or :class:`matplotlib.figure` or :class:`PIL.Image` or :class:`str`: * `TextDrawing` (output='text') @@ -2860,8 +2859,8 @@ def _rebind_definition( self._rebind_definition(inner.operation, parameter, value) def barrier(self, *qargs: QubitSpecifier, label=None) -> InstructionSet: - """Apply :class:`~qiskit.circuit.Barrier`. If qargs is empty, applies to all qubits in the - circuit. + """Apply :class:`~.library.Barrier`. If ``qargs`` is empty, applies to all qubits + in the circuit. Args: qargs (QubitSpecifier): Specification for one or more qubit arguments. @@ -2897,14 +2896,15 @@ def delay( qarg: Optional[QubitSpecifier] = None, unit: str = "dt", ) -> InstructionSet: - """Apply :class:`~qiskit.circuit.Delay`. If qarg is None, applies to all qubits. + """Apply :class:`~.circuit.Delay`. If qarg is ``None``, applies to all qubits. When applying to multiple qubits, delays with the same duration will be created. Args: duration (int or float or ParameterExpression): duration of the delay. qarg (Object): qubit argument to apply this delay. - unit (str): unit of the duration. Supported units: 's', 'ms', 'us', 'ns', 'ps', 'dt'. - Default is ``dt``, i.e. integer time unit depending on the target backend. + unit (str): unit of the duration. Supported units: ``'s'``, ``'ms'``, ``'us'``, + ``'ns'``, ``'ps'``, and ``'dt'``. Default is ``'dt'``, i.e. integer time unit + depending on the target backend. Returns: qiskit.circuit.InstructionSet: handle to the added instructions. @@ -3010,7 +3010,7 @@ def id(self, qubit: QubitSpecifier) -> InstructionSet: # pylint: disable=invali return self.i(qubit) def ms(self, theta: ParameterValueType, qubits: Sequence[QubitSpecifier]) -> InstructionSet: - """Apply :class:`~qiskit.circuit.library.generalized_gates.gms.MSGate`. + """Apply :class:`~qiskit.circuit.library.MSGate`. For the full matrix form of this gate, see the underlying gate documentation. @@ -3131,9 +3131,9 @@ def rv( rotation in radians. Args: - vx: x-compenent of the rotation axis. - vy: y-compenent of the rotation axis. - vz: z-compenent of the rotation axis. + vx: x-component of the rotation axis. + vy: y-component of the rotation axis. + vz: z-component of the rotation axis. qubit: The qubit(s) to apply the gate to. Returns: @@ -3564,8 +3564,8 @@ def cswap( target_qubit2: The qubit(s) targeted by the gate. label: The string label of the gate in the circuit. ctrl_state: - The control state in decimal, or as a bitstring (e.g. '1'). Defaults to controlling - on the '1' state. + The control state in decimal, or as a bitstring (e.g. ``'1'``). Defaults to controlling + on the ``'1'`` state. Returns: A handle to the instructions created. @@ -3906,10 +3906,10 @@ def mcx( The multi-cX gate can be implemented using different techniques, which use different numbers of ancilla qubits and have varying circuit depth. These modes are: - - 'noancilla': Requires 0 ancilla qubits. - - 'recursion': Requires 1 ancilla qubit if more than 4 controls are used, otherwise 0. - - 'v-chain': Requires 2 less ancillas than the number of control qubits. - - 'v-chain-dirty': Same as for the clean ancillas (but the circuit will be longer). + - ``'noancilla'``: Requires 0 ancilla qubits. + - ``'recursion'``: Requires 1 ancilla qubit if more than 4 controls are used, otherwise 0. + - ``'v-chain'``: Requires 2 less ancillas than the number of control qubits. + - ``'v-chain-dirty'``: Same as for the clean ancillas (but the circuit will be longer). For the full matrix form of this gate, see the underlying gate documentation. @@ -3984,10 +3984,10 @@ def mct( The multi-cX gate can be implemented using different techniques, which use different numbers of ancilla qubits and have varying circuit depth. These modes are: - - 'noancilla': Requires 0 ancilla qubits. - - 'recursion': Requires 1 ancilla qubit if more than 4 controls are used, otherwise 0. - - 'v-chain': Requires 2 less ancillas than the number of control qubits. - - 'v-chain-dirty': Same as for the clean ancillas (but the circuit will be longer). + - ``'noancilla'``: Requires 0 ancilla qubits. + - ``'recursion'``: Requires 1 ancilla qubit if more than 4 controls are used, otherwise 0. + - ``'v-chain'``: Requires 2 less ancillas than the number of control qubits. + - ``'v-chain-dirty'``: Same as for the clean ancillas (but the circuit will be longer). For the full matrix form of this gate, see the underlying gate documentation. @@ -4362,10 +4362,10 @@ def for_loop( There are two forms for calling this function. If called with all its arguments (with the possible exception of ``label``), it will create a - :obj:`~qiskit.circuit.controlflow.ForLoopOp` with the given ``body``. If ``body`` (and + :class:`~qiskit.circuit.ForLoopOp` with the given ``body``. If ``body`` (and ``qubits`` and ``clbits``) are *not* passed, then this acts as a context manager, which, when entered, provides a loop variable (unless one is given, in which case it will be - reused) and will automatically build a :obj:`~qiskit.circuit.controlflow.ForLoopOp` when the + reused) and will automatically build a :class:`~qiskit.circuit.ForLoopOp` when the scope finishes. In this form, you do not need to keep track of the qubits or clbits you are using, because the scope will handle it for you. @@ -4460,7 +4460,7 @@ def if_test( There are two forms for calling this function. If called with all its arguments (with the possible exception of ``label``), it will create a - :obj:`~qiskit.circuit.controlflow.IfElseOp` with the given ``true_body``, and there will be + :obj:`~qiskit.circuit.IfElseOp` with the given ``true_body``, and there will be no branch for the ``false`` condition (see also the :meth:`.if_else` method). However, if ``true_body`` (and ``qubits`` and ``clbits``) are *not* passed, then this acts as a context manager, which can be used to build ``if`` statements. The return value of the ``with`` @@ -4547,7 +4547,7 @@ def if_else( clbits: Sequence[ClbitSpecifier], label: Optional[str] = None, ) -> InstructionSet: - """Apply :class:`~qiskit.circuit.controlflow.IfElseOp`. + """Apply :class:`~qiskit.circuit.IfElseOp`. .. note:: @@ -4592,7 +4592,7 @@ def if_else( return self.append(IfElseOp(condition, true_body, false_body, label), qubits, clbits) def break_loop(self) -> InstructionSet: - """Apply :class:`~qiskit.circuit.controlflow.BreakLoopOp`. + """Apply :class:`~qiskit.circuit.BreakLoopOp`. .. warning:: @@ -4622,7 +4622,7 @@ def break_loop(self) -> InstructionSet: return self.append(BreakLoopOp(self.num_qubits, self.num_clbits), self.qubits, self.clbits) def continue_loop(self) -> InstructionSet: - """Apply :class:`~qiskit.circuit.controlflow.ContinueLoopOp`. + """Apply :class:`~qiskit.circuit.ContinueLoopOp`. .. warning:: @@ -4632,8 +4632,8 @@ def continue_loop(self) -> InstructionSet: determined. This would quickly lead to invalid circuits, and so if you are trying to construct a reusable loop body (without the context managers), you must also use the non-context-manager form of :meth:`.if_test` and :meth:`.if_else`. Take care that the - :obj:`.ContinueLoopOp` instruction must span all the resources of its containing loop, - not just the immediate scope. + :class:`~qiskit.circuit.ContinueLoopOp` instruction must span all the resources of its + containing loop, not just the immediate scope. Returns: A handle to the instruction created. diff --git a/qiskit/circuit/register.py b/qiskit/circuit/register.py index c8b7974e7e9..7038a7e9cd3 100644 --- a/qiskit/circuit/register.py +++ b/qiskit/circuit/register.py @@ -38,7 +38,13 @@ def __get__(self, obj, objtype=None): class Register: - """Implement a generic register.""" + """Implement a generic register. + + .. note:: + This class should not be instantiated directly. This is just a superclass + for :class:`~.ClassicalRegister` and :class:`~.QuantumRegister`. + + """ __slots__ = ["_name", "_size", "_bits", "_bit_indices", "_hash", "_repr"]