big refactor + documentation improvements + types refinements

Author: Henri-ColibrITD

docs/execution-extras.rst

@@ -31,7 +31,7 @@ __________
 Execution
 __________
 
-.. automodule:: mpqp.execution.providers_execution.ibm_execution
+.. automodule:: mpqp.execution.providers.ibm
 
 Atos/Eviden
 ^^^^^^^^^^^
@@ -44,12 +44,12 @@ __________
 Execution
 __________
 
-.. automodule:: mpqp.execution.providers_execution.atos_execution
+.. automodule:: mpqp.execution.providers.atos
 
 AWS
 ^^^
 
-.. automodule:: mpqp.execution.providers_execution.aws_execution
+.. automodule:: mpqp.execution.providers.aws
 
 Connection
 __________

example/notebooks/Notebook_1__Basics_of_circuit.ipynb examples/notebooks/Notebook_1__Basics_of_circuit.ipynb

@@ -1,7 +1,7 @@
 # pyright: reportUnusedImport=false
 import numpy as np
 
-from mpqp.execution.providers_execution.atos_execution import get_result_from_qlm_job_id
+from mpqp.execution.providers.atos import get_result_from_qlm_job_id
 
 from . import Barrier, Instruction, Language, QCircuit
 from .execution import (

example/notebooks/Notebook_2__Execution_Bell_circuit.ipynb examples/notebooks/Notebook_2__Execution_Bell_circuit.ipynb

@@ -412,8 +412,7 @@ def optimize(self, criteria: Optional[str | list[str]] = None) -> QCircuit:
         ...
 
     def to_matrix(self) -> npt.NDArray[np.complex64]:
-        """
-        Compute the unitary matrix associated to this circuit.
+        """Compute the unitary matrix associated to this circuit.
 
         Examples:
             >>> c = QCircuit([H(0), CNOT(0,1)])
@@ -670,6 +669,7 @@ def to_other_language(
                     qargs = range(instruction.size)
                 else:
                     raise ValueError(f"Instruction not handled: {instruction}")
+                assert not isinstance(qiskit_inst, Operator)
 
                 new_circ.append(
                     qiskit_inst,

example/notebooks/Notebook_3__Expectation_value_of_observables.ipynb examples/notebooks/Notebook_3__Expectation_value_of_observables.ipynb

@@ -47,19 +47,23 @@
 
 
 @typechecked
-def _qiskit_parameter_adder(param: Expr | float, qiskit_parameters: set[Parameter]):
+def _qiskit_parameter_adder(
+    param: Expr | float, qiskit_parameters: set[Parameter]
+) -> Parameter | float | int:
     """To avoid having several parameters in qiskit for the same value we keep
     track of them in a set. This function takes care of this, this way you can
     directly call `QiskitGate(_qiskit_parameter_adder(<param>, <q_params_set>))`
     without having to manually take care of the de-duping.
 
+    This process is a form of memoization.
+
     Args:
         param: The parameter you need for your qiskit gate.
         qiskit_parameters: The set of previously set qiskit parameters. This set
         is updated inplace.
 
     Returns:
-
+        The memoized parameter
     """
     if isinstance(param, Expr):
         name = str(param)
@@ -520,8 +524,7 @@ def __repr__(self):
 
 
 class CNOT(InvolutionGate, NoParameterGate, ControlledGate):
-    """
-    Two-qubit Controlled-NOT gate.
+    """Two-qubit Controlled-NOT gate.
 
     Args:
         control: index referring to the qubit used to control the gate

example/notebooks/Notebook_4__Quantum_Fourier_Transform.ipynb examples/notebooks/Notebook_4__Quantum_Fourier_Transform.ipynb

@@ -10,8 +10,8 @@
 
 from abc import ABC
 from copy import deepcopy
-from typing import Optional
 from numbers import Complex
+from typing import Optional
 
 from sympy import Expr, symbols  # pyright: ignore [reportUnusedImport]
 from typeguard import typechecked
@@ -29,11 +29,11 @@
 
 @typechecked
 class ParametrizedGate(Gate, ABC):
-    """
-    Define a parametrized gate.
+    """Define a parametrized gate.
 
     Args:
-        definition: Provide a definition of the gate (matrix, gate combination, ...).
+        definition: Provide a definition of the gate (matrix, gate combination,
+            ...).
         targets: List of indices referring to the qubits on which the gate will
             be applied.
         parameters: List of parameters used to define the gate.

example/notebooks/Notebook_5__Variational_Quantum_Algorithms.ipynb examples/notebooks/Notebook_5__Variational_Quantum_Algorithms.ipynb

@@ -9,6 +9,7 @@
 :class:`ComputationalBasis` and :class:`HadamardBasis`."""
 
 from __future__ import annotations
+
 from abc import abstractmethod
 from functools import reduce
 from typing import Optional
@@ -17,7 +18,7 @@
 import numpy.typing as npt
 from typeguard import typechecked
 
-from mpqp.tools.maths import matrix_eq, atol
+from mpqp.tools.maths import atol, matrix_eq
 
 
 @typechecked
@@ -107,8 +108,7 @@ def __init__(self, nb_qubits: Optional[int] = None):
 
     @abstractmethod
     def set_size(self, nb_qubits: int):
-        """
-        To allow the user to use a basis without having to specify the size
+        """To allow the user to use a basis without having to specify the size
         (because implicitly the size should be the number of qubits of the
         circuit), we use this method, that will only be called once the
         circuit's size is definitive (i.e. at the last moment before the circuit

example/scripts/CNOT_cascade_v_pairs.py examples/scripts/CNOT_cascade_v_pairs.py

@@ -1,11 +1,6 @@
 from __future__ import annotations
-from typing import Optional
 
-from mpqp.core.instruction.gates import (
-    KrausRepresentation,
-    PauliDecomposition,
-)
-from mpqp.core.languages import Language
+from typing import Optional
 
 import numpy as np
 import numpy.typing as npt
@@ -14,15 +9,17 @@
 # from qat.lang.AQASM import Program, H, PH, CNOT, SWAP, RX
 from qat.quops.quantum_channels import QuantumChannelKraus
 
-# QISKIT
-
 # Import from Qiskit Aer noise module
 from qiskit_aer.noise import depolarizing_error
 
+from mpqp.core.instruction.gates import KrausRepresentation, PauliDecomposition
+from mpqp.core.languages import Language
+
+# QISKIT
+
 
 class GateNoise:
-    """
-    A class used to apply Noise on a specific Gate
+    """A class used to apply Noise on a specific Gate.
 
     Noise can be defined in several ways, and this class allows us apply a
     specific qubit quantum error to a selected gate
@@ -42,6 +39,7 @@ class GateNoise:
 
     #This will go in the MPQPNoiseModel class
     hw_model = HardwareModel(gates_spec, gates_noise, idle_noise=None)
+    # 3M-TODO : implement and comment
 
     """
 
@@ -53,23 +51,25 @@ def __init__(
 
 
 class GateNoiseCombination:
-    """
-    A class that allows to combine different types of Noise on a selected Gate(s)
-    by using composition, tensor product, and tensor expansion and thus produces a
-    new quantum error.
+    """A class that allows to combine different types of Noise on a selected
+    Gate(s) by using composition, tensor product, and tensor expansion and thus
+    produces a new quantum error.
 
 
     Args:?
-        matrix : unitary matrix representing the gate
-        gate_combination : combination of gates (sum, product, ...) defining the gate
-        kraus_operators : generalized Kraus representation of the gate
-        pauli_decomposition : when it is possible, decomposition of the gate in the Pauli basis (I, X, Y, Z)
-        nb_qubits : number of qubits of the gate defined
+        matrix: Unitary matrix representing the gate.
+        gate_combination: Combination of gates (sum, product, ...) defining the
+            gate.
+        kraus_operators : Generalized Kraus representation of the gate.
+        pauli_decomposition: When it is possible, decomposition of the gate in
+            the Pauli basis (I, X, Y, Z).
+        nb_qubits: Number of qubits of the gate defined.
 
         more has to be added here, once it is thought through
 
     Attributes:
-        _current_type (str): string describing which definition is currently used to define the gate
+        _current_type (str): string describing which definition is currently
+        used to define the gate
 
 
     """
@@ -80,21 +80,23 @@ def __init__(self):
 
 
 class NoiseModules:
-    """
-    A class that contains function and methods for noise modeling.
+    """A class that contains function and methods for noise modeling.
 
 
     Args:
-        matrix : unitary matrix representing the gate
-        gate_combination : combination of gates (sum, product, ...) defining the gate
-        kraus_operators : generalized Kraus representation of the gate
-        pauli_decomposition : when it is possible, decomposition of the gate in the Pauli basis (I, X, Y, Z)
-        nb_qubits : number of qubits of the gate defined
+        matrix: Unitary matrix representing the gate.
+        gate_combination: Combination of gates (sum, product, ...) defining the
+            gate.
+        kraus_operators: Generalized Kraus representation of the gate.
+        pauli_decomposition: When it is possible, decomposition of the gate in
+            the Pauli basis (I, X, Y, Z)?
+        nb_qubits: Number of qubits of the gate defined.
 
         more has to be added here, once it is thought through
 
     Attributes:
-        _current_type (str): string describing which definition is currently used to define the gate
+        _current_type (str): String describing which definition is currently
+            used to define the gate.
 
 
     """
@@ -107,7 +109,8 @@ def __init__(self, nb_qubits: int, param: float, language: str):
     def depolarizing_error(
         self, param: float, num_qubits: int, language: Language = Language.QISKIT
     ):
-        """
+        """Depol error.
+
         Args:
             param: depolarizing error parameter.
             num_qubits: the number of qubits for the error channel.

example/scripts/aws_execution_trials.py examples/scripts/aws_execution_trials.py

@@ -92,8 +92,7 @@ def get_aws_braket_account_info() -> str:
 
 @typechecked
 def get_braket_device(device: AWSDevice) -> BraketDevice:
-    """
-    Returns the AwsDevice device associate with the AWSDevice in parameter.
+    """Returns the AwsDevice device associate with the AWSDevice in parameter.
 
     Example:
         >>> device = get_braket_device(AWSDevice.BRAKET_RIGETTI_ASPEN_M_3)
@@ -107,7 +106,8 @@ def get_braket_device(device: AWSDevice) -> BraketDevice:
         device: AWSDevice element describing which remote/local AwsDevice we want.
 
     Raises:
-        AWSBraketRemoteExecutionError
+        AWSBraketRemoteExecutionError: If the device or the region could not be
+            retrieved.
     """
 
     if not device.is_remote():

example/scripts/bell_pair.py examples/scripts/bell_pair.py

@@ -19,8 +19,7 @@
 
 @typechecked
 def config_ibm_account(token: str):
-    """
-    Configure and save locally IBM Quantum account's information.
+    """Configure and save locally IBM Quantum account's information.
 
     Args:
         token: IBM Quantum API token.
@@ -128,8 +127,8 @@ def get_IBMProvider() -> IBMProvider:
 
 
 def get_QiskitRuntimeService() -> QiskitRuntimeService:
-    """
-    Returns the QiskitRuntimeService needed for remote connection and execution
+    """Returns the QiskitRuntimeService needed for remote connection and
+    execution.
 
     Example:
         >>> service = get_QiskitRuntimeService()
@@ -141,7 +140,8 @@ def get_QiskitRuntimeService() -> QiskitRuntimeService:
          <RuntimeJob('cm7vds4pduldih1k1mq0', 'sampler')>]
 
     Raises:
-        IBMRemoteExecutionError
+        IBMRemoteExecutionError: When the ``qiskit`` runtime is not configured
+            or the configuration cannot be retrieved.
     """
     global Runtime_Service
     if Runtime_Service is None:
@@ -160,8 +160,7 @@ def get_QiskitRuntimeService() -> QiskitRuntimeService:
 
 
 def get_active_account_info() -> str:
-    """
-    Returns the information concerning the active IBMQ account
+    """Returns the information concerning the active IBMQ account.
 
     Example:
         >>> print(get_active_account_info())
@@ -172,7 +171,7 @@ def get_active_account_info() -> str:
             Verify: True
 
     Returns:
-        A string describing the account info.
+        The description containing the account information.
     """
     provider = get_IBMProvider()
     account = provider.active_account()
@@ -186,8 +185,8 @@ def get_active_account_info() -> str:
 
 @typechecked
 def get_backend(device: IBMDevice) -> BackendV1:
-    """
-    Retrieves the IBM Q remote device corresponding to the device in parameter
+    """Retrieves the IBM Q remote device corresponding to the device in
+    parameter.
 
     Args:
         device: The IBMDevice to get from IBMQ provider.
@@ -199,10 +198,11 @@ def get_backend(device: IBMDevice) -> BackendV1:
          Nduv(datetime.datetime(2024, 1, 9, 15, 41, 39, tzinfo=tzlocal()), gate_length, ns, 60)]
 
     Returns:
-        A qiskit.providers.backend.Backend object that will be use to execute circuit.
+        The requested backend.
 
     Raises:
-        IBMRemoteExecutionError
+        ValueError: If the required backend is a local simulator.
+        IBMRemoteExecutionError: If the device was not found.
     """
     # NOTE:
     #       Question : when a backend is present in several IBMQ instances, which instance does it use to submit jobs
@@ -228,9 +228,8 @@ def get_backend(device: IBMDevice) -> BackendV1:
 
 
 def get_all_job_ids() -> list[str]:
-    """
-    Retrieves all the job ids of this account from the several IBM remote providers
-    (IBMProvider, QiskitRuntimeService, ...)
+    """Retrieves all the job ids of this account from the several IBM remote
+    providers (IBMProvider, QiskitRuntimeService, ...).
 
     Example:
         >>> get_all_job_ids()

example/scripts/circuit_to_qasm.py examples/scripts/circuit_to_qasm.py

@@ -9,9 +9,7 @@
 
 
 def print_config_info():
-    """
-    Prints the info concerning each provider's registered account
-    """
+    """Prints the info concerning each provider's registered account."""
     print("===== IBM Quantum info : ===== ")
     try:
         print(ibmqc.get_active_account_info())