Merge 6ee9b7a into d6e4d52

doc/requirements.txt

@@ -9,3 +9,4 @@ numpydoc==1.4.0
 matplotlib==3.5.2
 docutils==0.17.1
 sphinxcontrib-bibtex==2.4.2
+qiskit==0.37.2

doc/source/apidoc.rst

@@ -33,3 +33,16 @@ Simulation based on the master equation.
    qutip_qip.compiler
    qutip_qip.pulse
    qutip_qip.noise
+
+Qiskit Circuit Simulation
+--------------------------
+Simulation of qiskit circuits based on qutip_qip backends.
+
+.. autosummary::
+   :toctree: apidoc/
+   :template: autosummary/module.rst
+
+   qutip_qip.qiskit.backend
+   qutip_qip.qiskit.converter
+   qutip_qip.qiskit.provider
+   qutip_qip.qiskit.job

doc/source/apidoc/qutip_qip.qiskit.rst

@@ -0,0 +1,56 @@
+:orphan:
+
+qutip\_qip.qiskit.backend
+===========================
+
+.. automodule:: qutip_qip.qiskit.backend
+   :members:
+   :show-inheritance:
+
+   .. rubric:: Classes
+
+   .. autosummary::
+
+      QiskitSimulatorBase
+      QiskitCircuitSimulator       
+      QiskitPulseSimulator     
+
+qutip\_qip.qiskit.converter
+==============================
+
+.. automodule:: qutip_qip.qiskit.converter
+   :members:
+   :show-inheritance:
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      convert_qiskit_circuit       
+
+qutip\_qip.qiskit.provider
+===========================
+
+.. automodule:: qutip_qip.qiskit.provider
+   :members:
+   :show-inheritance:
+
+   .. rubric:: Classes
+
+   .. autosummary::
+
+      Provider       
+
+qutip\_qip.qiskit.job
+===========================
+
+.. automodule:: qutip_qip.qiskit.job
+   :members:
+   :show-inheritance:
+
+   .. rubric:: Classes
+
+   .. autosummary::
+
+      Job
+

doc/source/index.rst

@@ -23,6 +23,7 @@ qutip-qip |version|: QuTiP quantum information processing
     qip-simulator.rst
     qip-processor.rst
     qip-vqa.rst
+    qip-qiskit.rst
 
 .. toctree::
     :maxdepth: 2

doc/source/qip-qiskit.rst

@@ -0,0 +1,126 @@
+.. _qip_qiskit:
+
+**********************************
+`qutip-qip` as a Qiskit backend
+**********************************
+
+This submodule was implemented by `Shreyas Pradhan <shpradhan12@gmail.com>`_ as part of Google Summer of Code 2022.
+
+Overview
+===============
+
+This submodule provides an interface to simulate circuits made in qiskit.
+
+Gate-level simulation on qiskit circuits is possible with :class:`.QiskitCircuitSimulator`. Pulse-level simulation is possible with :class:`.QiskitPulseSimulator` which supports simulation using the :class:`.LinearSpinChain`, :class:`.CircularSpinChain` and :class:`.DispersiveCavityQED` pulse processors.
+
+Running a qiskit circuit with qutip_qip
+==========================================
+
+After constructing a circuit in qiskit, either of the qutip_qip based backends (:class:`.QiskitCircuitSimulator` and :class:`.QiskitPulseSimulator`) can be used to run that circuit.
+
+Example
+--------
+
+Let's try constructing and simulating a qiskit circuit.
+
+We define a simple circuit as follows:
+
+.. code-block::
+
+    from qiskit import QuantumCircuit
+    
+    circ = QuantumCircuit(2,2)
+    circ.h(0)
+    circ.h(1)
+    
+    circ.measure(0,0)
+    circ.measure(1,1)
+
+Let's run this on the :class:`.QiskitCircuitSimulator` backend:
+
+.. code-block::
+
+    from qutip_qip.qiskit.provider import QiskitCircuitSimulator
+
+    backend = QiskitCircuitSimulator()
+    job = backend.run(circ)
+    result = job.result()
+    
+.. code-block:: 
+
+    from qiskit.visualization import plot_histogram
+    >>> plot_histogram(result.get_counts())
+
+.. image:: /figures/qiskit-gate-level-plot.png
+    :alt: probabilities plot 
+
+Now, let's run the same circuit on :class:`.QiskitPulseSimulator`.
+
+While using a pulse processor, we define the circuit without measurements:
+
+.. code-block:: 
+
+    pulse_circ = QuantumCircuit(2,2)
+    pulse_circ.h(0)
+    pulse_circ.h(1)
+
+To use the :class:`.QiskitPulseSimulator` backend, we need to define the processor on which we want to run the circuit. This includes defining the pulse processor model with all the required parameters including noise. 
+
+.. code-block::
+
+    from qutip_qip.device import LinearSpinChain
+    processor = LinearSpinChain(num_qubits=2)
+
+Now that we defined our processor (:class:`.LinearSpinChain` in this case), we can use it to perform the simulation: 
+
+.. code-block::
+
+    from qutip_qip.qiskit.provider import QiskitPulseSimulator
+
+    pulse_backend = QiskitPulseSimulator(processor)
+    pulse_job = pulse_backend.run(pulse_circ)
+    pulse_result = pulse_job.result()
+
+.. code-block::
+
+    >>> plot_histogram(pulse_result.get_counts())
+
+.. image:: /figures/qiskit-pulse-level-plot.png
+    :alt: probabilities plot
+
+Configurable Options
+========================
+
+Qiskit's interface allows us to provide some options like ``shots`` while running a circuit on a backend. We also have provided some options for the qutip_qip backends.
+
+``shots``
+-------------
+(Available for both: :class:`.QiskitCircuitSimulator` and :class:`.QiskitPulseSimulator`)
+``shots`` is the number of times measurements are sampled from the simulation result. By default it is set to ``1024``.
+
+``allow_custom_gate``
+-----------------------
+(Only available for :class:`.QiskitCircuitSimulator`)
+``allow_custom_gate``, when set to ``False``, does not allowing simulating circuits that have user-defined gates; it will throw an error in that case. By default, it is set to ``True``, in which case, the backend will simulate a user-defined gate by computing its unitary matrix.
+
+  .. note::
+
+    The pulse backend does not allow simulation with user-defined gates.
+
+An example demonstrating configuring options:
+
+.. code-block::
+
+    backend = QiskitCircuitSimulator()
+    job = backend.run(circ, shots=3000)
+    result = job.result()
+
+We provided the value of shots explicitly, hence our options for the simulation are set as: ``shots=3000`` and ``allow_custom_gate=True``.
+
+Another example:
+
+.. code-block::
+    
+    backend = QiskitCircuitSimulator()
+    job = backend.run(circ, shots=3000, allow_custom_gate=False)
+    result = job.result()

src/qutip_qip/device/cavityqed.py

@@ -88,9 +88,7 @@ def __init__(
         self, num_qubits, num_levels=10, correct_global_phase=True, **params
     ):
         model = CavityQEDModel(
-            num_qubits=num_qubits,
-            num_levels=num_levels,
-            **params,
+            num_qubits=num_qubits, num_levels=num_levels, **params
         )
         super(DispersiveCavityQED, self).__init__(
             model=model, correct_global_phase=correct_global_phase
@@ -167,6 +165,48 @@ def load_circuit(self, qc, schedule_mode="ASAP", compiler=None):
         self.global_phase = compiler.global_phase
         return tlist, coeff
 
+    def generate_init_processor_state(
+        self, init_circuit_state: Qobj = None
+    ) -> Qobj:
+        """
+        Generate the initial state with the dimensions of the DispersiveCavityQED processor.
+
+        Parameters
+        ----------
+        init_circuit_state : :class:`qutip.Qobj`
+            Initial state provided with the dimensions of the circuit.
+
+        Returns
+        -------
+        :class:`qutip.Qobj`
+            Return the initial state with the dimensions of the DispersiveCavityQED processor model.
+            If initial_circuit_state was not provided, return the zero state.
+        """
+        if init_circuit_state is None:
+            return basis(
+                [self.num_levels] + [2] * self.num_qubits,
+                [0] + [0] * self.num_qubits,
+            )
+        return tensor(basis(self.num_levels, 0), init_circuit_state)
+
+    def get_final_circuit_state(self, final_processor_state: Qobj) -> Qobj:
+        """
+        Truncate the final processor state to get rid of the cavity subsystem.
+
+        Parameters
+        ----------
+        final_processor_state : :class:`qutip.Qobj`
+            State provided with the dimensions of the DispersiveCavityQED processor model.
+
+        Returns
+        -------
+        :class:`qutip.Qobj`
+            Return the truncated final state with the dimensions of the circuit.
+        """
+        return final_processor_state.ptrace(
+            range(1, len(final_processor_state.dims[0]))
+        )
+
 
 class CavityQEDModel(Model):
     """

src/qutip_qip/device/modelprocessor.py

@@ -3,7 +3,7 @@
 
 import numpy as np
 
-from qutip import Qobj, QobjEvo, tensor, mesolve
+from qutip import Qobj, QobjEvo, tensor, mesolve, basis
 from ..operations import globalphase
 from ..circuit import QubitCircuit
 from .processor import Processor
@@ -243,6 +243,45 @@ def load_circuit(self, qc, schedule_mode="ASAP", compiler=None):
         self.set_tlist(tlist)
         return tlist, coeffs
 
+    def generate_init_processor_state(
+        self, init_circuit_state: Qobj = None
+    ) -> Qobj:
+        """
+        Generate the initial state with the dimensions of the processor.
+
+        Parameters
+        ----------
+        init_circuit_state : :class:`qutip.Qobj`
+            Initial state provided with the dimensions of the circuit.
+
+        Returns
+        -------
+        :class:`qutip.Qobj`
+            Return the initial state with the dimensions
+            of the processor model. If initial_circuit_state
+            was not provided, return the zero state.
+        """
+        if init_circuit_state is None:
+            return basis([2] * self.num_qubits, [0] * self.num_qubits)
+        return init_circuit_state
+
+    def get_final_circuit_state(self, final_processor_state: Qobj) -> Qobj:
+        """
+        Convert the state with the dimensions of the processor model to
+        a state with the dimensions of the circuit.
+
+        Parameters
+        ----------
+        final_processor_state : :class:`qutip.Qobj`
+            State provided with the dimensions of the processor model.
+
+        Returns
+        -------
+        :class:`qutip.Qobj`
+            Return the final state with the dimensions of the circuit.
+        """
+        return final_processor_state
+
 
 def _to_array(params, num_qubits):
     """