Skip to content

Commit

Permalink
[SDS-NNN] Some documentation improvements
Browse files Browse the repository at this point in the history
  • Loading branch information
@QFer
QFer committed Jun 22, 2021
1 parent 81afdb9 commit 0ff4a31
Show file tree
Hide file tree
Showing 5 changed files with 75 additions and 47 deletions.
4 changes: 2 additions & 2 deletions src/quantuminspire/job.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ class QuantumInspireJob:
def __init__(self, api: Any, job_identifier: int) -> None:
""" Encapsulation of a job.
The QuantumInspire Job class encapsulates the base job of the API and has
The QuantumInspireJob class encapsulates the base job of the API and has
methods to check the status and retrieve the results from the API.
:param api: An instance to the API.
Expand All @@ -48,7 +48,7 @@ def __check_arguments(api: Any, job_identifier: int) -> None:
:param api: An instance to the API.
:param job_identifier: The job identification number.
:raises ValueError: When the api is not a QuantumInspireApi or when the
:raises ValueError: When the api is not a QuantumInspireAPI or when the
job identifier is not found.
"""
if type(api).__name__ != 'QuantumInspireAPI':
Expand Down
6 changes: 3 additions & 3 deletions src/quantuminspire/projectq/backend_qx.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -143,7 +143,7 @@ def three_qubit_gates(self) -> Tuple[Any, ...]:
return self._three_qubit_gates

def cqasm(self) -> str:
""" Return cqasm code that is generated last. """
""" Return cQASM code that is generated last. """
return self._cqasm

@property
Expand Down Expand Up @@ -211,14 +211,14 @@ def _allocate_qubit(self, index_to_add: int) -> None:
:attr:`_allocation_map` is the store in which the administration
is done for assigning physical qubits that are used
with in ProjectQ to the simulation qubits, this is as they appear in the cqasm.
with in ProjectQ to the simulation qubits, this is as they appear in the cQASM.
:attr:`_allocation_map` stores the assignments as tuples (simulation_bit, physical_bit)
where 'physical_bit' is requested by ProjectQ and simulation_bit is the assignment to a bit in the simulator.
A de-allocated physical bit is registered as -1, which means the corresponding simulation bit can be re-used.
We strive for x-to-x allocation for qubits, which means we want to allocate a physical qubit to its
corresponding simulation qubit. We do this to respect as much as possible the qubits of the original algorithm
in the generated cqasm for readability.
in the generated cQASM for readability.
Only when the requested physical bit is higher than the max number of bits supported by the backend, we try
to search for an de-allocatd ancilla bit to re-use. When an ancilla is re-used, we have to reset the qubit
Expand Down
52 changes: 26 additions & 26 deletions src/quantuminspire/qiskit/backend_qx.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -61,30 +61,30 @@ def __init__(self, api: QuantumInspireAPI, provider: Any,
:param api: The interface instance to the Quantum Inspire API.
:param provider: Provider for this backend.
:param configuration: The configuration of the quantum inspire backend. The
:param configuration: The configuration of the Quantum Inspire backend. The
configuration must implement the fields given by the QiSimulatorPy.DEFAULT_CONFIGURATION. All
configuration fields are listed in the table below. The table rows with an asterisk specify fields which
can have a custom value and are allowed to be changed according to the description column.
=============== ============= =========================================================================
Key Type Description
=============== ============= =========================================================================
backend_name * str The name of the quantum inspire backend. The API can list the name of
each available backend using the function api.list_backend_types(). One
of the listed names must be used.
backend_version str Backend version in the form X.Y.Z.
n_qubits int Number of qubits.
basis_gates list[str] A list of basis gates to compile to.
gates GateConfig List of basis gates on the backend. Not used.
local bool Indicates whether the system is running locally or remotely.
simulator bool Specifies whether the backend is a simulator or a quantum system.
conditional bool Backend supports conditional operations.
open_pulse bool Backend supports open pulse. False.
memory bool Backend supports memory. True.
max_shots int Maximum number of shots supported.
max_experiments int Optional: Maximum number of experiments (circuits) per job.
coupling_map (list(tuple)) Define the edges.
=============== ============= =========================================================================
=================== ============= =====================================================================
Key Type Description
=================== ============= =====================================================================
``backend_name`` * str The name of the Quantum Inspire backend. The API can list the name of
each available backend using the function api.list_backend_types().
One of the listed names must be used.
``backend_version`` str Backend version in the form X.Y.Z.
``n_qubits`` int Number of qubits.
``basis_gates`` list[str] A list of basis gates to compile to.
``gates`` GateConfig List of basis gates on the backend. Not used.
``local`` bool Indicates whether the system is running locally or remotely.
``simulator`` bool Specifies whether the backend is a simulator or a quantum system.
``conditional`` bool Backend supports conditional operations.
``open_pulse`` bool Backend supports open pulse. False.
``memory`` bool Backend supports memory. True.
``max_shots`` int Maximum number of shots supported.
``max_experiments`` int Optional: Maximum number of experiments (circuits) per job.
``coupling_map`` (list(tuple)) Define the edges.
=================== ============= =====================================================================
"""
super().__init__(configuration=(configuration or
QuantumInspireBackend.DEFAULT_CONFIGURATION),
Expand All @@ -99,7 +99,7 @@ def backend_name(self) -> str:
def run(self, qobj: QasmQobj) -> QIJob:
""" Submits a quantum job to the Quantum Inspire platform.
:param qobj: The quantum job with the Qiskit algorithm and quantum inspire backend.
:param qobj: The quantum job with the Qiskit algorithm and Quantum Inspire backend.
:return:
A job that has been submitted.
Expand Down Expand Up @@ -243,7 +243,7 @@ def get_experiment_results_from_all_jobs(self, qi_job: QIJob) -> List[Experiment
def __validate_number_of_shots(self, job: QasmQobj) -> None:
""" Checks whether the number of shots has a valid value.
:param job: The quantum job with the Qiskit algorithm and quantum inspire backend.
:param job: The quantum job with the Qiskit algorithm and Quantum Inspire backend.
:raises QisKitBackendError: When the value is not correct.
"""
Expand Down Expand Up @@ -394,12 +394,12 @@ def __qubit_to_classical_hex(qubit_register: str, measurements: Dict[str, Any],
def __convert_histogram(result: Dict[str, Any], measurements: Dict[str, Any]) -> Dict[str, float]:
"""Convert histogram
The quantum inspire backend always uses full state projection. The SDK user
The Quantum Inspire backend always uses full state projection. The SDK user
can measure not all qubits and change the combined classical bits. This function
converts the result to a histogram output that represents the probabilities
measured with the classical bits.
:param result: The result output from the quantum inspire backend with full-
:param result: The result output from the Quantum Inspire backend with full-
state projection histogram output.
:param measurements: The dictionary contains a measured qubits/classical bits map (list) and the
number of classical bits (int).
Expand All @@ -423,7 +423,7 @@ def __convert_result_data(self, result: Dict[str, Any], measurements: Dict[str,
List[str]]:
"""Conver result data
The quantum inspire backend returns the single shot values as raw data. This function
The Quantum Inspire backend returns the single shot values as raw data. This function
converts this list of single shot values to hexadecimal memory data according the Qiskit spec.
From this memory data the counts histogram is constructed by counting the single shot values.
Expand All @@ -446,7 +446,7 @@ def __convert_result_data(self, result: Dict[str, Any], measurements: Dict[str,
When random is in the range [0.7, 1) the last value of the probability histogram is taken (0x6).
:param result: The result output from the quantum inspire backend with full-
:param result: The result output from the Quantum Inspire backend with full-
state projection histogram output.
:param measurements: The dictionary contains a measured qubits/classical bits map (list) and the
number of classical bits (int).
Expand Down
56 changes: 42 additions & 14 deletions src/quantuminspire/qiskit/qi_job.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,25 +29,52 @@

class QIJob(BaseJob): # type: ignore
"""
A job that is to be executed on the Quantum-inspire platform. A QIJob is normally created by calling run on the
QuantumInspireBackend but can also be recreated using a job_id:
A Qiskit job that is executed on the Quantum Inspire platform. A QIJob is normally created by calling
``execute`` (which triggers a `run` on the QuantumInspireBackend ``qi_backend``).
.. code::
qc = QuantumCircuit(5, 5)
qc.h(0)
qc.cx(0, range(1, 5))
qc.measure_all()
job = execute(qc, qi_backend, shots=1024)
result = job.result()
The return value of ``execute`` is an instance of QIJob (Qiskit job) and is the equivalent to the Quantum
Inspire project. It is a container to handle one or more (asynchronous) Qiskit circuits or experiments.
A Qiskit circuit is equivalent to a Quantum Inspire job.
To get the Quantum Inspire project-id from ``job`` do:
.. code::
qi_project_id = job.job_id()
To get the list of Quantum Inspire jobs (in dictionary format) from ``job`` do:
.. code::
qi_jobs = job.get_jobs()
QIJob can also be recreated using a ``job_id``, being a Quantum Inspire project-id:
.. code::
qi_backend = QI.get_backend('QX single-node simulator')
job = qi_backend.retrieve_job(job_id)
result = job.result()
"""

def __init__(self, backend: Any, job_id: str, api: QuantumInspireAPI, qobj: Optional[QasmQobj] = None) -> None:
"""
Construct a new QIJob object. Not normally called directly, use a backend object to create/retrieve jobs.
A QIJob object is normally not constructed directly.
:param backend: A quantum-inspire backend.
:param job_id: Id of the job as provided by the quantum-inspire api.
:param api: A quantum-inspire api.
:param qobj: A qiskit quantum object.
:param backend: A Quantum Inspire backend.
:param job_id: Id of the job as provided by the Quantum Inspire API.
:param api: A Quantum Inspire API.
:param qobj: A Qiskit quantum object.
"""
self._api: QuantumInspireAPI = api
super().__init__(backend, job_id)
Expand All @@ -62,14 +89,15 @@ def __init__(self, backend: Any, job_id: str, api: QuantumInspireAPI, qobj: Opti

def set_job_id(self, job_id: str) -> None:
""" Overwrite the job_id with a new id.
:param job_id: New id for the QIJob. Used in the use case for linking the job to the user-given QI project that
must contain the job.
"""
self._job_id = job_id

def submit(self) -> None:
"""
Submit a job to the quantum-inspire platform.
Submit a job to the Quantum Inspire platform.
:raises JobError: An error if the job has already been submitted.
"""
Expand All @@ -83,7 +111,7 @@ def _result(self, result_function: Callable[[BaseJob], List[ExperimentResult]],
:param result_function: backend function for fetching the requested results.
:param timeout: Timeout in seconds.
:param wait: Wait time between queries to the quantum-inspire platform.
:param wait: Wait time between queries to the Quantum Inspire platform.
:return:
Result object containing results from the experiments.
Expand All @@ -106,7 +134,7 @@ def result(self, timeout: Optional[float] = None, wait: float = 0.5) -> QIResult
""" Return the result for the experiments in the latest run for this project.
:param timeout: Timeout in seconds.
:param wait: Wait time between queries to the quantum-inspire platform.
:param wait: Wait time between queries to the Quantum Inspire platform.
:return:
QIResult object containing the result.
Expand All @@ -120,7 +148,7 @@ def result_all_jobs(self, timeout: Optional[float] = None, wait: float = 0.5) ->
""" Return the result for the experiments for all the existing jobs in the project.
:param timeout: Timeout in seconds.
:param wait: Wait time between queries to the quantum-inspire platform.
:param wait: Wait time between queries to the Quantum Inspire platform.
:return:
QIResult object containing the result.
Expand All @@ -135,7 +163,7 @@ def cancel(self) -> None:
self._api.delete_project(int(self._job_id))

def get_jobs(self) -> List[Dict[str, Any]]:
""" Gets the jobs that were submitted in the latest run. These job were added with add_job.
""" Gets the Quantum Inspire jobs that were submitted in the latest run. These job were added with add_job.
:return:
List of jobs with their properties for the jobs that were added for the experiments submitted when running
Expand All @@ -148,7 +176,7 @@ def get_jobs(self) -> List[Dict[str, Any]]:
return ret

def add_job(self, job: QuantumInspireJob) -> None:
""" Add a quantum inspire job to the list. The list contains the (quantum inspire) jobs created for the
""" Add a Quantum Inspire job to the list. The list contains the (Quantum Inspire) jobs created for the
submitted experiments in this particular QIJob.
:param job: QuatumInspireJob (submitted) that has to be added to the list of jobs created for the experiments
Expand Down
4 changes: 2 additions & 2 deletions src/quantuminspire/qiskit/qi_result.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,8 @@ class QIResult(Result): # type: ignore
"""
A result object returned by QIJob:
qi_backend = QI.get_backend('QX single-node simulator')
qi_job = qi_backend.retrieve_job(job_id)
qi_result = qi_job.result()
job = qi_backend.retrieve_job(job_id)
qi_result = job.result()
"""
def __init__(self, backend_name: str, backend_version: str, qobj_id: str, job_id: str, success: bool,
results: List[ExperimentResult], date: Any = None, status: Any = None, header: Any = None,
Expand Down

0 comments on commit 0ff4a31

Please sign in to comment.