Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Some doc formatting and link, mostly on quantumcircuit.py file #9771

Merged
merged 13 commits into from
Mar 16, 2023
2 changes: 1 addition & 1 deletion qiskit/algorithms/optimizers/qnspsa.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
4 changes: 4 additions & 0 deletions qiskit/circuit/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -263,6 +263,8 @@
AncillaRegister
AncillaQubit
CircuitInstruction
Register
Bit
1ucian0 marked this conversation as resolved.
Show resolved Hide resolved

Gates and Instructions
----------------------
Expand Down Expand Up @@ -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

Expand Down
8 changes: 7 additions & 1 deletion qiskit/circuit/bit.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"}

Expand Down
2 changes: 1 addition & 1 deletion qiskit/circuit/controlflow/for_loop.py
Original file line number Diff line number Diff line change
Expand Up @@ -142,7 +142,7 @@ class ForLoopContext:
from qiskit import QuantumCircuit
qc = QuantumCircuit(2, 1)

with qc.for_loop(None, range(5)) as i:
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a bug in doc that is it not being exposed.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For the record for others: this is deliberately not exposed documentation - it's an internal private detail of the control-flow builder interface. I just wrote some documentation in the docstrings of the private components for developers who are modifying the code. If we build a "developer documentation" / "architecture" section in the future, we could potentially put it there, but for now it's fine just being effectively a code comment.

with qc.for_loop(range(5)) as i:
qc.rx(i * math.pi/4, 0)
qc.cx(0, 1)
qc.measure(0, 0)
Expand Down
7 changes: 3 additions & 4 deletions qiskit/circuit/instruction.py
Original file line number Diff line number Diff line change
Expand Up @@ -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__()

Expand Down
8 changes: 4 additions & 4 deletions qiskit/circuit/instructionset.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
72 changes: 36 additions & 36 deletions qiskit/circuit/quantumcircuit.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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`:
1ucian0 marked this conversation as resolved.
Show resolved Hide resolved

* `TextDrawing` (output='text')
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Comment on lines +2905 to +2907
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Personally I don't think that all these need to be in monospace font (the strings are clear on their own), but I don't mind that much.


Returns:
qiskit.circuit.InstructionSet: handle to the added instructions.
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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).
Comment on lines -3909 to +3912
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same comment here about maybe not needing monospace, but again, not important.


For the full matrix form of this gate, see the underlying gate documentation.

Expand Down Expand Up @@ -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).
Comment on lines -3987 to +3990
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

... and here.


For the full matrix form of this gate, see the underlying gate documentation.

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you wanted to change the :obj: everywhere, there's another here too. I think for :class: it shouldn't make much of a difference, though.

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``
Expand Down Expand Up @@ -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::

Expand Down Expand Up @@ -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::

Expand Down Expand Up @@ -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::

Expand All @@ -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.
Expand Down
8 changes: 7 additions & 1 deletion qiskit/circuit/register.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"]

Expand Down